Skip to main content
The storefront Product Search APIs return the products for search results pages and category listing pages, along with the facets shoppers use to narrow those results. This guide explains which endpoint to call, how the main query parameters work, and how to combine them. For the full parameter list, see the Site Search and Search Products API reference. All examples use this base URL:
Examples show query strings without URL encoding so they are easier to read. URL-encode parameter values (spaces, colons, brackets, and the tilde in tenant~ attribute names) when you send real requests.

​
Choose an Endpoint

The two search endpoints accept the same query, filter, sort, paging, facet, and Merchandizing parameters. They differ in what they return and in how page size limits apply (see Page Size Limits):
  • siteSearch returns only the fields you request, so responses stay small. It uses the keyword search page size limit whether or not you pass query.
  • search runs as a keyword search when you pass a query value, and as a listing (browse) request when you do not. The page size limit depends on which one it is.

​
Core Parameters

​
query

The shopper’s search terms. When query is present, Kibo applies your search settings, synonyms, spell correction, and search term redirects.
If the query matches a search term redirect, the response contains a searchRedirect URL and no product results. Send the shopper to that URL.

​
filter

A filter expression that limits results, using the same operators as other Kibo APIs: eq, ne, gt, ge, lt, le, sw, cont, in[...], between[...], and and/or with parentheses for grouping. Custom attributes use their fully qualified name, such as tenant~color.
Escape special characters in filter values with a caret. For the full operator list, escaping rules, and the locationsInStock filter, see Sorting and Filtering APIs and Product Storefront Location Filter. Use filter for conditions your page sets (such as the current category). Use facetValueFilter for values the shopper picks from the facet list, so the facet keeps showing the other values the shopper can add.

​
sortBy

A field name followed by asc or desc, for example sortBy=price desc or sortBy=createDate desc. Separate multiple sorts with commas. If you omit sortBy, Kibo uses its default ordering, including any Merchandizing rule that applies. Passing sortBy turns off Merchandizing rule matching for that request, including a rule you name with merchandizingRuleCode. See Merchandizing Rules.

​
Paging with startIndex and pageSize

startIndex is the zero-based offset of the first result. pageSize is the number of results to return. To show page 3 with 24 products per page:
The response includes totalCount, startIndex, pageSize, and pageCount for building pagination controls.

​
Deep paging with cursorMark

To walk through a large result set, such as when exporting every product in a category, use cursorMark instead of startIndex:
  1. Send the first request with cursorMark=*.
  2. Read nextCursorMark from the response.
  3. Send the same request again with cursorMark set to that value.
  4. Stop when the response has no nextCursorMark.
Keep every other parameter the same between calls. cursorMark works on both siteSearch and search.

​
Page Size Limits

The 10,000 maximum for keyword searches is a tenant setting. Kibo can raise or lower it for your tenant with the search-sitesearch-pagesize-limit tenant attribute. Contact Kibo Support to change it. Large pages are slower to build and return. For storefront pages, keep pageSize close to the number of products you display. For exports, use cursorMark with a moderate page size.

​
Facets

Facets let shoppers narrow results by category, price, brand, or any attribute that is set up for faceting in the search schema. The same request that returns products also returns a facets array, so you do not need a separate call. Each facet in the response has a label, a field, a facetType, and a values array. Each value has a label, a value, a count, an isApplied flag, and a filterValue. Category facets also include childrenFacetValues.

​
facetTemplate

Loads the facets configured in the Admin for a category (see Facets). The format is categoryCode:{code} or categoryId:{id}.
A category’s facet template includes the facets defined on that category, on its parent categories, and on the root template. On a keyword search results page with no category context, use categoryCode:_root. This loads the root template, which holds the facets configured for search results.

​
facet

A comma-separated list of extra fields to facet on, in addition to the template. Use the attribute’s fully qualified name for custom attributes.
Add omitNamespace=true to pass and receive attribute names without the tenant~ prefix.

​
facetTemplateSubset and facetTemplateExclude

Both take a comma-separated list of facet field names from the template:
  • facetTemplateSubset returns only the listed facets.
  • facetTemplateExclude returns every template facet except the listed ones.
If you pass both, Kibo uses facetTemplateExclude and ignores facetTemplateSubset.

​
Apply a Facet Value

When a shopper selects a facet value, pass that value’s filterValue from the response in facetValueFilter. The format is field:value. Separate multiple values with commas.
Values for the same field are combined with OR. Values for different fields are combined with AND. The example above returns jackets that are blue or black and are made by Acme. The applied values come back with isApplied: true.

​
Range Facets and facetFieldRangeQuery

A range facet groups numeric values, such as price, into buckets. Ranges set up in the facet template are used automatically. To build a range facet on the fly, pass facetFieldRangeQuery with one or more field:[start TO end] ranges. Use * for an open end.
If the template already defines ranges for the field, the template ranges are used instead. To filter on a range facet, pass the range in facetValueFilter. The range does not have to match one of the defined buckets, so you can support a price slider:

​
Category Facets: facetHierValue and facetHierDepth

The category facet is hierarchical. Two parameters control which part of the category tree it returns:
  • facetHierValue sets the category to start from, as categoryCode:{code} or categoryId:{id}. The facet then returns that category and its subcategories instead of the whole tree. Use categoryCode:_root to start from the top of the tree.
  • facetHierDepth limits how many levels of subcategories are returned, as categoryCode:{levels} or categoryId:{levels}. With 0, only the starting category is returned. With 1, its direct subcategories are included.
Use the same field name (categoryCode or categoryId) as the category facet in your template.

​
Facet Value Sort and Prefix

  • facetValueSort sorts the values of a facet, as field:sortType. Valid sort types are CountAscending, CountDescending, ValuesAscending, ValuesDescending, AttributeDefinition, AttributeDefinitionDescending, Count, and Index. Facets from a template use the sort set in the template. The default for other facets is CountDescending.
  • facetPrefix returns only values that start with a prefix, as field:prefix.

​
Spell Correction

When spell correction is turned on in your search configuration, keyword searches can correct misspelled queries:
  • Autocorrect: if the query returns no results and a correction exists, Kibo runs the corrected query instead. The response spellcheck object has autoCorrected: true, the originalQuery, and the correctedQuery.
  • Did you mean: the response spellcheck.candidateCorrections lists suggested queries you can offer to the shopper.
Use spellcorrectOverride to turn these off for a single request:

​
Merchandizing Rules

Merchandizing rules boost, bury, pin, or block products for a search term or category. Kibo picks the matching rule for you:
  • For a keyword search, Kibo matches the rule by the query value.
  • For a request without a query value, Kibo matches the rule by category when filter limits results to a single category.
To apply a specific rule instead of the matched one, pass its code in merchandizingRuleCode:
Rules apply only when the request has no sortBy value. The named rule also needs a search term or a single-category filter on the request. When a Merchandizing rule applies, personalization ranking is not applied to that request.

​
Choose the Response Fields

​
fieldList (siteSearch)

siteSearch returns only productCode for each item unless you list more fields in fieldList. Common fields include productName, priceL, priceH, productImageUrls, categoryCode, productShortDescription, and custom attribute names. See Site Search API for more examples.

​
responseFields

responseFields trims the JSON response on any Kibo API, including both search endpoints. For example, responseFields=totalCount,items(productCode,content(productName)),facets on search. See Limit Data Returned from API Calls for the syntax.

​
Worked Examples

​
Keyword Search Results Page

​
Category Listing Page with a Selected Facet and Sort

​
Price Slider

​
In Stock at a Store

​
Export Every Product in a Category

Repeat with cursorMark set to each nextCursorMark until the response has none.