List of APIs
Search APIs
Search Refinements
Upload Data
Search Navigations
Null Search Terms
Search Term Performance
Search Products
Trending Searches

About Our APIs

The GroupBy set of APIs allow you implement and enable Search, provide recommendations, search as you type (SAYT) capabilities, analytics, and all support needed to build headless eCommerce solutions.

Available APIs

Search APIs

A complete guide on preparing and sending your data, in a way that creates great relevance.

Recommendation APIs

Optimize relevancy with rules, smart navigations, content, recommendations, event tracking, and personalization.

Analytics APIs

Get the best out of your Search. Learn how to analyze user activity. See what you can do with Analytics.

Quick Start

This section will help you understand the basic requirements essential to send test request to our API endpoints.

You can customize these examples by using your own:

  • API Key
  • Area
  • Collection
  • Query Parameters

Once these parameters are customized, you can send a test request and view the response.

Once you finalize the request, you can convert it into various languages suitable to your coding needs.


  1. You have an account at and have an endpoint that allows you to upload and query data
  2. You have administrative access to your Command Center
  3. You have access to Customer ID and API Key from Command Center

API Versioning

The API has a version number in the URL https://…/v1/… This version number is different from the version number that you may see in Command Center. All released versions of command center are compatible with three back version of the API.

Product line

This product line follows the version naming model laid out by the semantic version practice detailed here.

For example, version number 2.15.45 increments the:

  1. Major version when we make incompatible API changes - the API version is updated as well.
  2. Minor version when we add functionality in a backwards-compatible manner.
  3. Patch version when we make backwards-compatible bug fixes.

Status Codes And Warnings

The following document describes a list of error codes and warnings that you can receive from the GroupBy services.

General Responses

Code Name Description
401 Unauthorized The client key was either not provided or incorrect.
403 Forbidden The request was valid, but to a module endpoint that you are not authorized to access.
405 Method Not Allowed The incorrect POST/PUT/DELETE/GET was used for a specific service.
420 Client Error The user has attempted something not supported by the API.
500 Internal Server Error A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
503 Service Unavailable The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.
505 HTTP Version Not Supported The server does not support the HTTP protocol version used in the request.

Data API

Code Name Description
200 OK All data was uploaded and successfully inserted.
400 Bad Request The request cannot be fulfilled due to bad syntax. Typically, malformatted data. Check the response for more details.
408 Request Timeout The upload took longer than the allowable time for the server to process data.
411 Length Required The length of the data was not sent and is required.
415 Unsupported Media Type The data uploaded is not in one of the supported formats.
429 Too Many Requests To protect overall stability data uploads are only allowed a certain frequency.

Search API

Code Name Description
200 OK The search was performed successfully.
408 Request Timeout The search took longer than the allowable time for the server to process the search.
413 Request Entity Too Large The query string exceeds the allowable character limit and cannot be truncated.
429 Too Many Requests If the cloud console has placed an upper limit on queries per second, this will be enforced to prevent overages.