Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insider One Eureka Search Category Merchandising API
version: 1.0.0
description: 'Eureka product discovery: search results, search suggestions and category/brand merchandising collections.
Derived by API Evangelist from Insider One''s own public Postman collection ("Insider One APIs", published at https://developers.insiderone.com/). Paths, methods, headers, query parameters and request/response examples are verbatim from that collection; nothing is invented. The 429 response is documented for all Insider One APIs on https://academy.insiderone.com/docs/api-rate-limits-1 .'
contact:
name: Insider One Support
email: support@useinsider.com
url: https://academy.insiderone.com/docs/insider-one-apis-1
termsOfService: https://insiderone.com/terms-of-use/
servers:
- url: https://ineureka.api.useinsider.com
tags:
- name: Category Merchandising API
paths:
/api/web/collections:
get:
operationId: categoryCollection
summary: Category Collection
tags:
- Category Merchandising API
description: 'The Category Collection type in Eureka’s Category Merchandising API allows retrieval of all products in a specific category in the product catalog, helping narrow results by product type. For example, you can retrieve products under the "Footwear" category to get all shoes.
Structures
Flat Structure
Some catalogs use a non-hierarchical or flat category structure where categories are not nested (e.g., Shoes, Footwear instead of Women > Shoes > Sneakers). In this case, you can retrieve products within specific categories, such as Shoes.
Multiple Flat Category Retrieval
Only products belonging to both categories are returned when multiple singular categories are used in a flat category search. These categories are connected using an "AND" condition, meaning that a product must be classified under both to be included. For example, searching for Shoes and Footwear will return only products categorized as both Shoes and Footwear.
The cf parameter should be formatted the same way as in hierarchical structures, such as shoes or shoes~footwear
Merchandising rules cannot be applied to multiple flat category retrievals.
Hierarchical Structure
Some catalogs use a hierarchical category structure, where categories follow a parent-child relationship (e.g., Women > Shoes > Sneakers). In this case, searches should use the whole structure to ensure accurate results. For example, to retrieve products under Women > Shoes, use Women~Shoes.
You can select Flat or Hierarchical structure from Catalog Settings > Category Type page in the InOne panel.To use the Category Collection type, the category attribute in the product catalog must be properly populated to ensure product retrieval.
Request Parameters
The type path variable value must exactly match the example values provided in the request parameter table. The cf parameter value must exactly match the values defined in the product catalog.
Parameter
Description
Data Type
Required
Example
type
Path variable that specifies the desired product listing type
String
Yes
"Category"
cf
Allows filtering of products within the specified listing type
String
Yes
cf=Women~Shoes~Trainers
p
Partner ID. Navigate to Inone Settings > Account Settings to copy your Partner ID.
String
Yes
l
Locale is required to get your products in the current language of the website. E.g. en_US, en_GB
String
Yes
l=en_US
c
Products will be displayed in the given currency (The current currency selected by the end-user on your website). E.g., USD, AUD
String
Yes
c=USD
sid
Strategy ID. The unified identifier for a merchandising strategy. If Eureka Strategies(opens in new tab) are enabled for your account, you need to add this parameter to utilize the strategy. When provided, the listed products are enhanced with the merchandising rules belonging to the specified strategy. Merchandising actions such as boosting, burying, pinning, and hiding products are applied to category pages based on the rules defined within that strategy.
String
No
sid=123456
a
Filter the products with the following pattern: a={field}~{value}
List of String
No
a=size~38~39
pf
Index indicating from which order the products will start to be listed. It is used for pagination. The default value is pf=0.
Integer
No
ps
Number of products that will be returned in the response. The default value is ps=6.
Integer
No
st
Sorting type of the listed products. It only takes one of the predefined sorting types. The default value is st=Relevancy.
String
No
oi
The listed products will only be displayed as item IDs. The default value is oi=False
Boolean
No
oc
The listed products will be displayed without their variants. The default value is false.
Boolean
No
u
User ID can be found in local storage by the key name spUID. spUID, which is a stringified object and contains data and expired properties.
String
No
The sid (Strategy ID) parameter enables strategy-based merchandising. When a valid strategy ID is provided, the API applies the merchandising rules associated with that strategy to the search results. This includes product-level actions (boost, high-boost, bury, high-bury, pin, hide) and attribute-level actions (boost attribute, bury attribute, hide by attribute).- A Eureka Strategy(opens in new tab) becomes active once it is assigned to a Eureka Campaign. However, when using strategies with the Eureka Category API, a strategy can still be applied to category pages even if it is not assigned to any campaign and remains inactive. In this case, the strategy will take effect when the sid parameter is included in the API request.- **If sid is omitted, no strategy-based merchandising rules are applied to the search results.**- Additionally, if Eureka Strategies are enabled for your account, refer to the image below showing where to locate the sid:'
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
/api/web/collections/{type}:
get:
operationId: manageProductListingPages
summary: Manage product listing pages
tags:
- Category Merchandising API
description: "Eureka’s Category Merchandising API allows you to curate and manage your product listing pages effectively. Tailored for various list pages, such as categories, sales, new arrivals, and brands, enabling you to pin, boost, bury, or hide specific products as needed. You can set the rules using a visual merchandising editor to customize content for particular categories. Once you apply the rules, you can build the listing pages by making an API call based on the listing page type and its filters.\n\nThe initial step involves sending your data to Insider One in the correct format, typically handled by system rules defined during the website mapping process. \n\nCategory Merchandising API responses are in JSON format containing product matching criteria, configured merchandising content, and available facet options for further refinement.\n\nRequirements for Category Merchandising API\n\nFor product details, Insider One product catalog integration methods(opens in new tab) (XML, Catalog API, and Clickstream) should be created.\n\nData collection should be activated by the Insider One team.\n\nEureka should be activated by the Insider One team.\n\nIf you want to use dynamic filters (facets) and sortings in the category pages, you need to set these configurations via Eureka Settings in the Insider One's InOne panel.\n\nEndpoint\nhttps://ineureka.api.useinsider.com/api/web/collections/{type}?cf={COLLECTION_FILTER}&p={PARTNER_ID}&l={LOCALE}&c={CURRENCY} \n\nFor requests where the total URL length exceeds 2,048 characters, a POST request must be sent to the base URL: https://ineureka.api.useinsider.com/api/web/collections. While the HTTP protocol itself does not define an explicit maximum URL length, practical limitations exist across browsers, web servers, proxies, and load balancers.To prevent compatibility issues and request failures, we enforce the length threshold as a precautionary measure. Although GET requests may yield faster responses in some cases, it is important to transition to POST when the payload size approaches or exceeds approximately 2,000 characters.This ensures compliance with common platform constraints and avoids potential truncation, rejection, or undefined behavior resulting from excessively long URLs.\n\nThe only difference between GET and POST requests is that the values sent as URL parameters in GET requests must be sent as JSON body in POST requests. For example:\n\n{\n \"cf\": \"COLLECTION_FILTER\",\n \"p\": \"PARTNER_ID\",\n \"l\": \"LOCALE\",\n \"c\": \"CURRENCY\",\n \"sid\": \"STRATEGY_ID\"\n}\n\nWhen the request is sent, an authentication exception is thrown for security reasons. Therefore, when sending the request, you need to set the X-AUTH-TOKEN header to the token shared with you.\n\nCollection Types\nWhen retrieving products from the product catalog, three different collection types help organize and filter results based on specific criteria. These collection types are:\n\nCategory Collection\nThe Category Collection type enables the retrieval of all products in the catalog that belong to a specific category, helping to narrow down results based on product type. For example, to get all shoes, you can retrieve products under the \"Footwear\" category.\n\nBrand Collection\nThe Brand Collection(opens in new tab) type enables you to retrieve all products from a specific brand in the catalog, making it easy for users to access products from their preferred brands. For example, if you want to get all Nike products, you can use this option to retrieve only items from the \"Nike\" brand.\n\nAll Products Collection\nThe All Products Collection type allows the retrieval of all products in the catalog without any restrictions, providing access to the entire product catalog. For example, if you want to see all products, you can use this option to retrieve all products in the catalog.\n\nUsing these collection types, you can retrieve products efficiently based on your specific needs.\n\nCommon Capabilities for All Types\nSorting\nThe st parameter in the request can only have one value from the predefined sorting types. Using these types, the sorting algorithm for the listed products is selected. Depending on your data, the sorting types can be active or inactive. You can view these settings on the InOne panel.\n\nParameter\nSorting Type\n\nst\nRelevancy\n\nst\nPriceAsc\n\nst\nPriceDesc\n\nst\nMostPopularFirst\n\nst\nBestRatedFirst\n\nst\nMostRatedFirst\n\nst\nNewestFirst\n\nst\nMostFavoriteFirst\n\nst\nMostDiscountedFirst\n\nFilters\nYou can filter listed products using field names in the filter settings defined in faceting in Insider One's InOne panel.\n\nSample Faceting Regarding the Filter Config\nSample filter request:\n\n&a=category~Skin~Body Lotions&a=price~5~10\n\nIn the result of this filter request, you can see the matched facets in the related property sections of items as below:\n\n{\n \"itemProperties\": {\n \"item_card\": {\n \"price\": {\n \"EUR\": 7.75,\n ...\n },\n \"category\": [\n \"Skin\",\n \"Body Lotions\",\n ...\n ],\n \"in_stock\": 1,\n ...\n },\n ...\n },\n ...\n}\n\nThe field values you can use for facet filtering are provided under data.aggregations in the result.\n\n[\n {\n \"name\": \"price\",\n \"label\": \"Price\",\n \"style\": \"Slider\",\n \"items\": [\n {\n \"name\": \"0~5\",\n \"min\": 0.0,\n \"max\": 5.0\n },\n {\n \"name\": \"5~10\",\n \"min\": 5.0,\n \"max\": 10.0\n },\n ...\n ],\n \"sequence\": 1,\n \"itemOrderType\": \"KeyAsc\"\n },\n {\n \"name\": \"category\",\n \"label\": \"Category\",\n \"style\": \"List\",\n \"items\": [\n {\n \"name\": \"Skin\",\n \"selected\": true,\n \"documentCount\": 66\n },\n {\n \"name\": \"Body Lotion\",\n \"selected\": true,\n \"documentCount\": 61\n },\n ...\n ],\n \"sequence\": 2,\n \"itemOrderType\": \"CountDesc\"\n },\n {\n \"name\": \"in_stock\",\n \"label\": \"In Stock\",\n \"style\": \"Checkboxes\",\n \"items\": [\n {\n \"name\": \"1\",\n \"selected\": false,\n \"documentCount\": 12\n },\n ...\n ],\n \"sequence\": 3,\n \"itemOrderType\": \"CountDesc\"\n },\n ...\n]\n\nThis table details the facet filter styles and their corresponding data types. Based on the specific filter style you want to implement, choose the appropriate data type.\n\nFilter Style\nData Type\n\nPrice\nNumeric\n\nRating\nNumeric\n\nRange\nNumeric\n\nSlider\nNumeric\n\nCheckboxes\nString\n\nList\nString\n\nToggle\nBoolean\n\nFor the filters with numeric data types, such as Slider style, there should be only two values: min and max.\n\n{field}~{minValue}~{maxValue}\n\nSample Filter Parameters\n&a=brand~Neki snippet\n\n&a=category~Birds~Cats~Dogs\n\n&a=price~50~100\n\n&a=brand~Neki&a=price~50~100\n\nSample Responses\n\nParameter\nDefinition\n\nstatus\nIt is the field that shows the result of the search. This field can be: - Success: Category Merchandising API response is valid. - Error: Unexpected internal server errors. - Invalid: Eureka Category Merchandising API returns a Validation Exception. The request is invalid. - BusinessException: Eureka Category Merchandising API returns a Business Exception. Details are shared in Validation Exceptions section.\n\ndata\nIt is the object where items, sortings, aggregations, navigations, and noResultPageText are kept as a result of a given query.\n\ndata.items\nThis field holds the list of properties for the returned items.\n\ndata.items.itemId\nIt shows the item ID. * In case there are variants of the item, the ID refers to the item to be displayed in search results. The item details are kept under data.items.itemProperties in addition to that all the variants including the item displayed are also stored in data.items.itemVariants\n\ndata.items.itemProperties.item_card\nThis field holds all of the fields such as name, discount, product_attributes (which includes a list of fields such as flavor, color, etc.). * In case there are price and original_price fields, they are the same unless there is a discount on this product. When there is a discount, price field is equal to discounted price. * These fields may vary depending on your account.\n\ndata.items.itemVariants\nThis field holds all of the variants of an item. The first element of the list is the item to be displayed in search results. The format of data.items.itemVariants items is the same as the data.items.itemProperties.item_card. * Variants are options of the same item that have different properties. For instance, yellow and red color options of the same t-shirt might be variants of the t-shirt. * Use of variants may be active or passive depending on your account.\n\ndata.aggregations\nThis field holds a list of different aggregations.\n\ndata.aggregations.name\nThis field holds the aggregation name.\n\ndata.aggregations.label\nThis field holds the aggregation label (which is for showing the name of the aggregation to the end user).\n\ndata.aggregations.style\nThis field holds the aggregation style. Possible values: Price, Checkboxes, Toggle, Rating, Range, Slider, List\n\ndata.aggregations.items\nThis field holds a list of item fields for the specified aggregation.\n\ndata.aggregations.items.name\nThis field holds the aggregation item name.\n\ndata.aggregations.items.label\nThis field holds the aggregation item label.\n\ndata.aggregations.items.min\nThis field holds the minimum value of the aggregation item if the aggregation style is numeric.\n\ndata.aggregations.items.max\nThis field holds the maximum value of the aggregation item if the aggregation style is numeric.\n\ndata.aggregations.items.selected\nIt is a boolean field that indicates whether the aggregation item is selected if the aggregation style is not numeric.\n\ndata.aggregations.items.documentCount\nThis field holds the total number of documents of the aggregation item if the aggregation style is not numeric.\n\ndata.aggregations.suffixUnit\nThis field holds the suffix unit for the facet values as string. For instance, for perfume_size facets, ml is the suffixUnit (50ml - 100ml)\n\ndata.aggregations.prefixUnit\nThis field holds the prefix unit for the facet values as string.\n\ndata.aggregations.sequence\nThis field holds the sequence of the aggregation for showing the aggregations to the end-user in the correct order.\n\ndata.aggregations.itemOrderType\nThis field holds the item order type of the aggregation. Possible values: KeyAsc, KeyDesc, CountDesc, CountAsc, None\n\ndata.navigation\nThis dictionary shows information such as pagination and total item count.\n\ndata.navigation.totalPages\nThis field shows how many pages are returned for a given query.\n\ndata.navigation.currentPage\nThis field specifies which page the returned result is.\n\ndata.navigation.totalItems\nThis field shows how many items are returned for a given query.\n\ndata.navigation.itemPerPage\nIt is the field that shows how many items are returned on each page.\n\ndata.noResultPageText\nIf a query does not return any results, this field is used for the empty result page. E.g., No Results found\n\ndata.sortings\nIt is the list where the details about sorting are kept.\n\ndata.sortings.type\nIt is the field where the sorting type is located. Possible sorting types: Relevancy, PriceAsc, PriceDesc, MostPopularFirst, BestRatedFirst, MostRatedFirst, NewestFirst, MostFavoriteFirst, MostDiscountedFirst\n\ndata.sortings.label\nIt is the label of sorting that is displayed to the end user.\n\ndata.sortings.selected\nIt is a boolean field that indicates whether the relevant sorting is selected.\n\ndata.defaultSortingType\nIt is the field where the sorting type of the recommended items is located. It is null when no active sorting is found.\n\npartnerResources\nIt is the list of labels to be displayed to the end user. It provides localization flexibility based on the locale parameter sent. *Partner resources can be set from the InOne panel.\n\nerror\nWhen there is a business exception (501), this field is filled with code and message fields.\n\nvalidations\nWhen the request is incorrect (400 Bad Request), this field is filled with an array of type and message fields.\n\n200 Success\n{ \n \"status\": \"Success\",\n \"data\": {\n \"items\": [...],\n \"aggregations\": [...],\n \"navigation\": {...},\n \"noResultPageText\": \"...\",\n \"sortings\": [...]\n },\n \"redirection\": null,\n \"partnerResources\": {...},\n \"error\": null,\n \"validations\": null\n}\n\n500 Internal Server Error\n{ \n \"status\": \"Error\",\n \"data\": null,\n \"redirection\": null,\n \"partnerResources\": null,\n \"error\": {\n \"code\": \"500 INTERNAL_SERVER_ERROR\",\n \"message\": \"...\" \n },\n \"validations\": null\n}\n\n400 Business Exception\nYou can refer to the Fail Records Messages to troubleshoot the Business Exception errors.\n\n{ \n \"status\": \"BusinessException\",\n \"data\": null,\n \"redirection\": null,\n \"partnerResources\": null,\n \"error\": {\n \"code\": \"...\",\n \"message\": \"...\" \n },\n \"validations\": null\n}\n\n400 Validation Exception\nYou can refer to the Fail Records Messages to troubleshoot the Validation Exception errors.\n\n{ \n \"status\": \"Invalid\", \n \"data\": null, \n \"redirection\": null, \n \"partnerResources\": null,\n \"error\": null,\n \"validations\": [\n {\n \"type\": \"...\",\n \"message\": \"...\"\n }\n ]\n}\n\nFail Records Messages\n\nBusiness Exceptions\n\nMessage\nDefinition\nHTTP Code\n\nAggregationStyleNotFound\nAggregation style must be provided in the partner config.\n400\n\nAggregationConfigNotFound\nAggregation configs must be provided in the partner config.\n400\n\nSortingConfigNotFound\nSorting configs must be provided in the partner config\n400\n\nSortingFieldNotFound\nSorting field must be provided in the partner config.\n400\n\nInvalidPriceAggregationStyle\nIncorrect style for price aggregation is provided in the partner config.\n400\n\nPartnerConfigNotFound\nPartner config cannot be gathered from the cache.\n400\n\nAggregationResultNotFound\nUnexpected aggregation results were received according to aggregation configs.\n400\n\nValidation Exceptions\n\nMessage\nDefinition\nHTTP Code\n\nPartnerIdNotFound\np parameter is not provided in the request\n400\n\nLocaleNotFound\nl parameter is not provided in the request\n400\n\nLocaleInvalidFormat\nWrong locale format is provided in the request\n400\n\nCurrencyNotFound\nc parameter is not provided in the request\n400\n\nCurrencyInvalidFormat\nWrong currency format is provided in the request\n400\n\nCollectionFilterNotFound\nCollection filter cf is not provided\n400\n\nCollectionFilterInvalidFormat\nCollection filter format is invalid\n400\n\nInvalidCollectionFilter\nCollection filter must not be given with AllProducts Collection Type\n400\n\nCollectionInvalidLength\nCollection filter must contain number of characters between 2 and 280\n400\n\nPaginationFromInvalidValue\nWrong pf value is provided in the request\n400\n\nPaginationSizeInvalidValue\nWrong ps value is provided in the request\n400\n\nAggregationNameNotFound\nAggregation name must be provided in the request\n400\n\nAggregationItemsNotFound\nAggregation items must be provided in the request\n400\n\nSortingTypeInvalid\nSorting type is not valid\n400"
parameters:
- name: type
in: path
required: true
schema:
type: string
- name: cf
in: query
required: false
schema:
type: string
example: '{COLLECTION_FILTER}'
- name: p
in: query
required: false
schema:
type: string
example: '{PARTNER_ID}'
- name: l
in: query
required: false
schema:
type: string
example: '{LOCALE}'
- name: c
in: query
required: false
schema:
type: string
example: '{CURRENCY}'
responses:
'429':
$ref: '#/components/responses/TooManyRequests'
components:
responses:
TooManyRequests:
description: Too Many Requests. The published per-endpoint rate limit was exceeded; back off and retry, honouring Retry-After when present.
content:
application/json:
example:
message: Too Many Requests
status: 429
externalDocs:
description: Insider One API reference
url: https://academy.insiderone.com/docs/api-reference-welcome
x-provenance:
generated: '2026-08-13'
method: derived
source: postman/insider-one-apis.postman_collection.json
source_url: https://documenter.gw.postman.com/api/collections/24851117/2sB3dSR9bM
publisher_page: https://developers.insiderone.com/
note: Insider One publishes a single public Postman collection covering every REST API. This document is the subset of that collection served from ineureka.api.useinsider.com.
omitted:
- name: All Products Collection
reason: the published collection carries an empty URL for this request; nothing to derive