AI Search — API Reference

Powerful and configurable search, boosted by Synerise AI

56 endpoints across 8 tags.

Search

GET /search/v2/indices/{indexId}/query — Full-text items search

/api-reference/ai-search#tag/Search/operation/SearchFullTextGet

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
queryquerystringrequiredQuery text to use in the search
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
correlationIdquerystringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdquerystringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
disableQueryClassificationquerybooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerquerybooleanoptionalIf set to true, dynamic reranker is not applied.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/query?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/query — Full-text items search

/api-reference/ai-search#tag/Search/operation/SearchFullTextPost

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · items-search-FullTextSearchRequest

Request for performing full-text search

FieldTypeRequiredDescription
querystringrequiredQuery text to use in the search
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
personalizebooleanoptionalIf set to false, the search result is not personalized.
correlationIdstringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdstringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.
disableQueryClassificationbooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerbooleanoptionalIf set to true, q dynamic reranker is not applied.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/query \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"string","page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"},"disableQueryClassification":false,"disableDynamicReranker":false}'

GET /search/v2/indices/{indexId}/query/explain — Explained full-text items search

/api-reference/ai-search#tag/Search/operation/SearchFullTextGetWithExplanation

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
queryquerystringrequiredQuery text to use in the search
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
correlationIdquerystringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdquerystringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
disableQueryClassificationquerybooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerquerybooleanoptionalIf set to true, dynamic reranker is not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
crossWorkspaceModeEnabledquerybooleanoptionalIf set, overrides the cross-workspace mode from the index configuration. When true, cross-workspace personalization is enabled. When false, it is disabled.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/query/explain?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&crossWorkspaceModeEnabled=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/query/explain — Explained full-text items search

/api-reference/ai-search#tag/Search/operation/SearchFullTextPostWithExplanation

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · object

Request for performing full-text search with explanation

FieldTypeRequiredDescription
querystringrequiredQuery text to use in the search
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
personalizebooleanoptionalIf set to false, the search result is not personalized.
correlationIdstringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdstringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.
disableQueryClassificationbooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerbooleanoptionalIf set to true, q dynamic reranker is not applied.
crossWorkspaceModeobjectoptionalCross-workspace personalization mode. When provided, overrides the index configuration setting.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/query/explain \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"string","page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"},"disableQueryClassification":false,"disableDynamicReranker":false,"crossWorkspaceMode":{"enabled":true}}'

GET /search/v2/indices/{indexId}/autocomplete — Autocomplete items search

/api-reference/ai-search#tag/Search/operation/SearchAutocompleteGet

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
queryquerystringrequiredQuery text to use in the search
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
disableQueryClassificationquerybooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerquerybooleanoptionalIf set to true, dynamic reranker is not applied.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/autocomplete?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/autocomplete — Autocomplete items search

/api-reference/ai-search#tag/Search/operation/SearchAutocompletePost

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · items-search-AutocompleteRequest

Request for performing an autocomplete search

FieldTypeRequiredDescription
querystringrequiredQuery text to use in the search
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.
disableQueryClassificationbooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerbooleanoptionalIf set to true, q dynamic reranker is not applied.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/autocomplete \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"string","page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"},"disableQueryClassification":false,"disableDynamicReranker":false}'

GET /search/v2/indices/{indexId}/autocomplete/explain — Explained autocomplete items search

/api-reference/ai-search#tag/Search/operation/SearchAutocompleteGetWithExplanation

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
queryquerystringrequiredQuery text to use in the search
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
crossWorkspaceModeEnabledquerybooleanoptionalIf set, overrides the cross-workspace mode from the index configuration. When true, cross-workspace personalization is enabled. When false, it is disabled.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
disableQueryClassificationquerybooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerquerybooleanoptionalIf set to true, dynamic reranker is not applied.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/autocomplete/explain?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&crossWorkspaceModeEnabled=SOME_BOOLEAN_VALUE&params=source%3Amobile&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/autocomplete/explain — Explained autocomplete items search

/api-reference/ai-search#tag/Search/operation/SearchAutocompletePostWithExplanation

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · object

Request for performing an autocomplete search with explanation

FieldTypeRequiredDescription
querystringrequiredQuery text to use in the search
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.
disableQueryClassificationbooleanoptionalIf set to true, query classification is not applied.
disableDynamicRerankerbooleanoptionalIf set to true, q dynamic reranker is not applied.
crossWorkspaceModeobjectoptionalCross-workspace personalization mode. When provided, overrides the index configuration setting.

Responses

StatusDescription
200 application/jsonSearch result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/autocomplete/explain \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"string","page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"},"disableQueryClassification":false,"disableDynamicReranker":false,"crossWorkspaceMode":{"enabled":true}}'

GET /search/v2/indices/{indexId}/explain-match — Searchable attributes match

/api-reference/ai-search#tag/Search/operation/searchableAttributesMatch

Enter a query and an item ID to check if a token (a word or a synonym which replaced it) matches a value or part of a value from the item's searchable attributes.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation
queryquerystringrequiredQuery text to use in the search
itemIdquerystringrequiredItem ID

Responses

StatusDescription
200 application/jsonSearchable attributes match result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/explain-match?query=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/deleted-searches — Get deleted searches

/api-reference/ai-search#tag/Search/operation/GetDeletedSearches

Retrieve the searches deleted from a profile's history.

API consumers: AI API key (legacy), Workspace (Business Profile), Web SDK Tracker

API key permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index that the query relates to
clientUUIDquerystringrequiredUUID of the profile for which the query is performed

Responses

StatusDescription
200 application/jsonDeleted searches returned
400 application/jsonCheck error message for more details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/deleted-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/deleted-searches — Soft-delete a recent search

/api-reference/ai-search#tag/Search/operation/PostDeletedSearch

Delete a recent search from the history accessible to a profile. The search remains in the database and you can retrieve it by using this endpoint.

API consumers: AI API key (legacy), Workspace (Business Profile), Web SDK Tracker

API key permission required: ITEMS_SEARCH_RECENT_SEARCH_CREATE

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index that the query relates to
clientUUIDquerystringrequiredUUID of the profile for which the query is performed

Request body (required)

application/json · items-search-recent-DeletedSearch

Request for deleting search query

FieldTypeRequiredDescription
querystringoptionalDeleted search query. Required if match field is set to query.
matchstringoptionalTells how to match this deleted search on recent searches. query: matches only recent searches with provided query all: matches all recent searches
timestampstringoptionalTime when the search was deleted. If not present current time is taken.

Responses

StatusDescription
204Soft-delete successful
400 application/jsonCheck error message for more details

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/deleted-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query":"string","match":"query","timestamp":"2019-08-24T14:15:22Z"}'

GET /search/v2/indices/{indexId}/recent-searches — Get recent searches

/api-reference/ai-search#tag/Search/operation/GetRecentSearches

Get a profile's recent searches from a particular index.

API consumers: AI API key (legacy), Workspace (Business Profile), Web SDK Tracker

API key permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index that the query relates to
clientUUIDquerystringrequiredUUID of the profile for which the query is performed
windowSizequeryintegeroptionalMaximum number of recent searches to be returned. NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.
timeUnitqueryenum<"YEARS", "MONTHS", "WEEKS", "DAYS", …>optionalThe time unit. Used in conjunction with timeValue.NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.
timeValuequeryintegeroptionalThe amount of time units. Used in conjunction with timeUnit.NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.

Responses

StatusDescription
200 application/jsonRecent searches returned
400 application/jsonCheck error message for more details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/recent-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1&windowSize=SOME_INTEGER_VALUE&timeUnit=SOME_STRING_VALUE&timeValue=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Listing

GET /search/v2/indices/{indexId}/list — Items listing

/api-reference/ai-search#tag/Listing/operation/ListingGet

Retrieves item listing, which is a search without a query. The results can be filtered and sorted.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
correlationIdquerystringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdquerystringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

StatusDescription
200 application/jsonListing result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/list?clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/list — Items listing

/api-reference/ai-search#tag/Listing/operation/ListingPost

Retrieves item listing, which is a search without a query. The results can be filtered and sorted.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · items-search-ListingRequest

Request for item listing

FieldTypeRequiredDescription
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
personalizebooleanoptionalIf set to false, the search result is not personalized.
correlationIdstringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdstringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.

Responses

StatusDescription
200 application/jsonListing result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/list \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"}}'

GET /search/v2/indices/{indexId}/list/explain — Explained items listing

/api-reference/ai-search#tag/Listing/operation/ListingGetWithExplanation

Retrieves item listing, which is a search without a query. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation
clientUUIDquerystringoptionalUUID of the profile for which the search is performed
personalizequerybooleanoptionalIf set to false, the search result is not personalized.
correlationIdquerystringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdquerystringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricqueryenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsqueryarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusqueryintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersquerystringoptionalIQL query string. For details, see the Help Center.
facetsqueryarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
facetsSizequeryintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetqueryintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesquerybooleanoptionalSpecifies whether facets aggregation should be case sensitive.
displayAttributesqueryarray<string>optionalList of ad hoc attributes that will be returned for each found item
contextqueryarray<string>optionalList of context strings for a search query
includeFacetsqueryenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets parameter.
facetsOrderByqueryenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilterquerystringoptionalDistinctFilter JSON as an URL-encoded string
ignoreQueryRulesquerybooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesqueryarray<integer>optionalList of query rules that will not be applied.
crossWorkspaceModeEnabledquerybooleanoptionalIf set, overrides the cross-workspace mode from the index configuration. When true, cross-workspace personalization is enabled. When false, it is disabled.
paramsqueryarray<string>optionalList of extra params that will be added to the item.search event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

StatusDescription
200 application/jsonListing result
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/list/explain?clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&facetsOrderBy=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&crossWorkspaceModeEnabled=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/list/explain — Explained items listing

/api-reference/ai-search#tag/Listing/operation/ListingPostWithExplanation

Retrieves item listing, which is a search without a query. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers: AI API key (legacy), Web SDK Tracker, Workspace (Business Profile)

API key permission required: ITEMS_SEARCH_SEARCH_READ

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation

Request body (required)

application/json · object

Request for item listing with explanation

FieldTypeRequiredDescription
pageintegeroptionalPage number to return for pagination. The first page has the index 1.
limitintegeroptionalThe number of items to return per page
sortBystringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
orderingenum<"desc", "asc">optionalSorting order
includeMetabooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUIDstringoptionalUUID of the profile for which the search is performed
personalizebooleanoptionalIf set to false, the search result is not personalized.
correlationIdstringoptionalCorrelation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchIdstringoptionalDEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetricenum<"TransactionsPopularity", "PageVisitsPopularity">optionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPointsstringoptionalIMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point ({latitude},{longitude}) for data sorting. Results are sorted by distance from this point. ordering: asc means "closest first".'
filterGeoPointsarray<string>optionalThe definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the filterAroundRadius parameter. Example input: ["34.052235,-118.243685"] Given two geo-points, the results will be limited to a rectangular area. Example input: ["50,-100", "25,150"] Given three or more geo-points, the results will be limited to a polygonal area. Example input: ["50,0", "40,20", "-20,10"]
filterAroundRadiusintegeroptionalRadius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filtersstringoptionalIQL query string. For details, see the Help Center.
facetsarray<string>optionalA list of attributes for which facets will be returned. A single * value matches all facetable attributes. A single auto value enables automatic facet selection based on the result set — the system picks the most relevant facets using the index's dynamicFacets configuration. To determine which groups of facets should be returned, use the includeFacets parameter.
customFilteredFacetsobjectoptionalA key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSizeintegeroptionalDetermines how many items will be used for facets aggregation.
maxValuesPerFacetintegeroptionalDetermines how many values will be retrieved per facet.
caseSensitiveFacetValuesbooleanoptionalSpecifies whether facets aggregation should be case sensitive.
includeFacetsenum<"all", "filtered", "unfiltered", "none">optionalDetermines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the facets and customFilteredFacets parameters.
facetsOrderByenum<"coverage", "name">optionalControls the ordering of facets in the response.When facets=auto, the default ordering is by coverage (most relevant facets first).When facets are specified explicitly, the default ordering is by name.When two facets have equal coverage, ties are resolved by name.
contextarray<string>optionalList of context strings for a search query
displayAttributesarray<string>optionalList of ad hoc attributes that will be returned for each found item
distinctFilterobjectoptionalDistinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRulesbooleanoptionalIf set to true, query rules are not applied.
excludeQueryRulesarray<integer>optionalList of query rules that will not be applied.
paramsobjectoptionalExtra parameters that will be added to the item.search event. The total size must not exceed 500 bytes.
crossWorkspaceModeobjectoptionalCross-workspace personalization mode. When provided, overrides the index configuration setting.

Responses

StatusDescription
200 application/jsonListing result
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/list/explain \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"page":0,"limit":10,"sortBy":"string","ordering":"desc","includeMeta":true,"clientUUID":"string","personalize":true,"correlationId":"string","searchId":"string","sortByMetric":"TransactionsPopularity","sortByGeoPoints":"34.052235,-118.243685","filterGeoPoints":["34.052235,-118.243685","15.0,65.0"],"filterAroundRadius":2000,"filters":"string","facets":["string"],"customFilteredFacets":{"brand":"price > 100","price":"brand == foo"},"facetsSize":2000,"maxValuesPerFacet":50,"caseSensitiveFacetValues":false,"includeFacets":"all","facetsOrderBy":"coverage","context":["mobile","listing"],"displayAttributes":["title","price"],"distinctFilter":{"attribute":"string","maxNumItems":1,"levelRangeModifier":0},"ignoreQueryRules":false,"excludeQueryRules":[2,5],"params":{"source":"mobile"},"crossWorkspaceMode":{"enabled":true}}'

Synonyms

GET /search/v2/indices/{indexId}/synonyms — Get synonyms

/api-reference/ai-search#tag/Synonyms/operation/GetSynonymsV2

Retrieve a list of synonyms.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredIndex identifier
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalName of the attribute by which the data will be sorted and ordered by. Supported values: indexId, updatedAt, createdAt, confidence. Defaults to updatedAt.
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
sourcequeryenum<"User", "Agent", "Import">optionalFilter synonyms by source
statequeryenum<"New", "Accepted", "Pending", "Rejected">optionalFilter synonyms by state
typequeryenum<"oneway", "synonyms">optionalFilter synonyms by type
searchquerystringoptionalSearch synonyms by word or synonym phrase (case-insensitive partial match)
confidencequerynumberoptionalFilter synonyms with confidence greater than or equal to this value

Responses

StatusDescription
200 application/jsonList of synonyms returned
500 application/jsonSome error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms?page=4&limit=100&sortBy=confidence%3Aasc&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&source=SOME_STRING_VALUE&state=SOME_STRING_VALUE&type=SOME_STRING_VALUE&search=SOME_STRING_VALUE&confidence=SOME_NUMBER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/synonyms — Create synonym

/api-reference/ai-search#tag/Synonyms/operation/PostSynonymV2

Creates a new synonym.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_CREATE

User role permission required: assets_search: create

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredIndex identifier

Request body (required)

application/json · object

Request for creating new synonym

FieldTypeRequiredDescription
typeenum<"oneway", "synonyms">optionalType of the synonym. oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.
wordstringoptionalThe phrase that the synonym relates to. If type: synonyms, do not send this value.
synonymsarray<string>requiredA list of synonyms
confidencenumberoptionalConfidence score of the synonym (0.0 to 1.0)
reasonstringoptionalReason or explanation for the synonym suggestion
sourceenum<"User", "Agent", "Import">optionalOrigin of the synonym
stateenum<"New", "Accepted", "Pending", "Rejected">optionalCurrent state of the synonym

Responses

StatusDescription
200 application/jsonId of created synonym returned
500 application/jsonSome error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"oneway","word":"string","synonyms":["string"],"confidence":1,"reason":"string","source":"User","state":"New"}'

POST /search/v2/indices/{indexId}/synonyms/batch — Batch insert synonyms

/api-reference/ai-search#tag/Synonyms/operation/BatchSynonyms

Insert multiple synonyms into an index at once.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_CREATE

User role permission required: assets_search: create

Parameters

NameInTypeRequiredDescription
sourcequeryoptionalSource to assign to imported synonyms
indexIdpathstringrequiredIndex identifier

Request body (required)

text/csv · object

The CSV has three columns:

  • word: the phrase to replace with a synonym
  • synonyms: the synonyms of the word (if more than one, the list is comma-separated and enclosed with "")
  • type: the relation type:
    • oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms.
    • synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.
FieldTypeRequiredDescription
wordstringoptionalThe phrase that the synonym relates to. If type: synonyms, do not send this value.
synonymsarray<string>optionalA list of synonyms
typeenum<"oneway", "synonyms">optionalType of the synonym. oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.

Responses

StatusDescription
200 application/jsonSummary of batch insertion
500 application/jsonSome error occurred

Example request (cURL)

curl -X POST 'https://api.synerise.com/search/v2/indices/{indexId}/synonyms/batch' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

POST /search/v2/indices/{indexId}/synonyms/replace-all — Replace all synonyms

/api-reference/ai-search#tag/Synonyms/operation/ReplaceAllSynonyms

Deletes all existing synonyms from an index and then inserts multiple new synonyms at once.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredIndex identifier
sourcequeryoptionalSource to assign to imported synonyms

Request body (required)

text/csv · object

The CSV has three columns:

  • word: the phrase to replace with a synonym
  • synonyms: the synonyms of the word (if more than one, the list is comma-separated and enclosed with "")
  • type: the relation type:
    • oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms.
    • synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.
FieldTypeRequiredDescription
wordstringoptionalThe phrase that the synonym relates to. If type: synonyms, do not send this value.
synonymsarray<string>optionalA list of synonyms
typeenum<"oneway", "synonyms">optionalType of the synonym. oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.

Responses

StatusDescription
204All synonyms replaced
500 application/jsonSome error occurred

Example request (cURL)

curl -X POST 'https://api.synerise.com/search/v2/indices/{indexId}/synonyms/replace-all' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

GET /search/v2/indices/{indexId}/synonyms/{synonymId} — Get synonym

/api-reference/ai-search#tag/Synonyms/operation/GetSynonymV2

Retrieves a synonym.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
synonymIdpathintegerrequiredSynonym identifier
indexIdpathstringrequiredIndex identifier

Responses

StatusDescription
200 application/jsonSynonym returned.
500 application/jsonSome error occurred

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms/%7BsynonymId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PUT /search/v2/indices/{indexId}/synonyms/{synonymId} — Update synonym

/api-reference/ai-search#tag/Synonyms/operation/PutSynonym

Updates a synonym identified by id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
synonymIdpathintegerrequiredSynonym identifier
indexIdpathstringrequiredIndex identifier

Request body (required)

application/json · object

Request for creating new synonym

FieldTypeRequiredDescription
typeenum<"oneway", "synonyms">optionalType of the synonym. oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.
wordstringoptionalThe phrase that the synonym relates to. If type: synonyms, do not send this value.
synonymsarray<string>requiredA list of synonyms
confidencenumberoptionalConfidence score of the synonym (0.0 to 1.0)
reasonstringoptionalReason or explanation for the synonym suggestion
sourceenum<"User", "Agent", "Import">optionalOrigin of the synonym
stateenum<"New", "Accepted", "Pending", "Rejected">optionalCurrent state of the synonym

Responses

StatusDescription
200 application/jsonUpdated synonym returned.
500 application/jsonSome error occurred

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms/%7BsynonymId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"oneway","word":"string","synonyms":["string"],"confidence":1,"reason":"string","source":"User","state":"New"}'

DELETE /search/v2/indices/{indexId}/synonyms/{synonymId} — Delete synonym

/api-reference/ai-search#tag/Synonyms/operation/DeleteSynonymV2

Deletes a synonym with given id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SYNONYMS_SEARCH_DELETE

User role permission required: assets_search: delete

Parameters

NameInTypeRequiredDescription
synonymIdpathintegerrequiredSynonym identifier
indexIdpathstringrequiredIndex identifier

Responses

StatusDescription
204Synonym deleted
500 application/jsonSome error occurred

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms/%7BsynonymId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Search Configuration

GET /search/v2/indices/{indexId}/attributes/filterable/values — Get values of filterable attributes

/api-reference/ai-search#tag/Search-Configuration/operation/getFilterableAttributesValues

Retrieve values of filterable attributes.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index to be used in the search operation
attributequeryarray<string>requiredList of attributes for which values will be fetched

Responses

StatusDescription
200 application/jsonValues returned
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/attributes/filterable/values?attribute=SOME_ARRAY_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices — Get configurations of all indices

/api-reference/ai-search#tag/Search-Configuration/operation/getIndicesConfigsV2

Retrieve the configurations of all indices.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalName of the attribute by which the data will be sorted
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
namequerystringoptionalDeprecated parameter. If query is provided, this parameter is ignored. If an index has an id equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their name will be retrieved.
queryquerystringoptionalIf an index has an id equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their name will be retrieved. This parameter replaces the deprecated name parameter.
excludeAbTestsquerybooleanoptionalOnly indices not involved in currently running AB tests will be retrieved.
directoryIdquerystringoptionalRequested directoryId of the rule.
typequeryenum<"Keyword", "Hybrid", "Semantic">optionalRequested type of the rule.

Responses

StatusDescription
200 application/jsonConfigurations returned
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices?page=4&limit=100&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&name=SOME_STRING_VALUE&query=SOME_STRING_VALUE&excludeAbTests=SOME_BOOLEAN_VALUE&directoryId=SOME_STRING_VALUE&type=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices — Post index configuration

/api-reference/ai-search#tag/Search-Configuration/operation/postIndexConfigV2

Creates a new configuration of a single index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE

User role permission required: assets_search: create

Request body (required)

application/json · object

Request for posting search configuration

FieldTypeRequiredDescription
indexNamestringrequiredHuman-friendly name of the index
descriptionstringoptionalDescription of the index
itemsCatalogIdstringrequiredID of the item catalog from which the index will be created
languagestringrequiredSearch language as ISO 639-1 code
enabledbooleanrequiredWhen true, the index is enabled and can be queried.
ignoreUnavailableItemsbooleanoptionalWhen true, unavailable items are not indexed, which makes the search run faster.
scoringobjectoptionalItem scoring settings that affect the presentation order of the results. 0 means the lowest importance of a parameter, 1 is the highest importance.
suggestionsobjectoptionalControls manner in which suggestions are generated
tokenizeroptionalUsed for tokenizing full text into individual words
analyzersobjectoptionalControls analyzer settings.
attributesWithoutPrefixSearcharray<string>optionalSearchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerancearray<string>optionalSearchable attributes for which typo tolerance is off
valuesWithoutTypoTolerancearray<string>optionalAttributes values for which typo tolerance is off
typoToleranceOnNumericValuesbooleanoptionalWhen true, typo tolerance is active on numbers
searchableAttributesobjectrequiredThe attributes that are taken into account as full text search terms
displayableAttributesarray<string>optionalAttributes shown in the search results
facetableAttributesobjectoptionalAttributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
filterableAttributesobjectoptionalAttributes for which filters can be used
sortableAttributesobjectoptionalAttributes using which search results can be sorted
distinctFilterAttributesobjectoptionalAttributes for which distinct can be used
recentSearchesobjectoptionalRecent searches configuration
rerankingobjectoptionalReranking configuration
geoSearchobjectoptionalGeo search configuration
queryRulesobjectoptionalConfiguration for custom behavior of query rules at the index level.

Responses

StatusDescription
200 application/jsonReturned created configuration
500 application/jsonService not available

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"indexName":"string","description":"string","itemsCatalogId":"string","language":"string","enabled":true,"ignoreUnavailableItems":true,"scoring":{"pageVisitsPopularity":0,"transactionsPopularity":0,"personalized":0,"tieBreaker":0,"matching":{"type":"MinimumMatching","value":1},"fallbackMatching":{"type":"MinimumMatching","value":1},"similarity":{"type":"BM25","k1":1.2,"b":0.75},"crossWorkspaceMode":{"enabled":true}},"suggestions":{"smoothingModel":"Popularity","gramSize":3,"maxErrors":2,"minWordLength":4,"useAlways":false},"tokenizer":{"type":"Whitespace"},"analyzers":{"autocomplete":"Ngram"},"attributesWithoutPrefixSearch":["brand","color","promotion.type"],"attributesWithoutTypoTolerance":["itemId","link"],"valuesWithoutTypoTolerance":["Nike","blue","74997"],"typoToleranceOnNumericValues":true,"searchableAttributes":{"fullText":["brand","color","promotion.type"],"fullTextBoosted":["brand","color","promotion.type"],"fullTextStronglyBoosted":["brand","color","promotion.type"]},"displayableAttributes":["brand","color","promotion.type"],"facetableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"filterableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"sortableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"distinctFilterAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"recentSearches":{"windowSize":100,"timeSpan":{"type":"DAYS","value":30}},"reranking":{"dynamicReranker":{"enabled":true,"filter":"string","numberOfItems":1,"minNumberOfEvents":0},"queryClassification":{"enabled":true,"actions":[{"action":"staticFilter","minReliabilityLevel":"certain"}],"excludedPhrases":["string"],"excludedCategories":["string"]}},"geoSearch":{"geoSearchableAttribute":"string"},"queryRules":{"consequencesJoinOperators":{"standardFilters":"AND","elasticFilters":"AND"}}}'

GET /search/v2/indices/{indexId}/config — Get index configuration

/api-reference/ai-search#tag/Search-Configuration/operation/getIndexConfigV2

Retrieve the configuration of a single index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
200 application/jsonConfiguration returned
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PUT /search/v2/indices/{indexId}/config — Update index configuration

/api-reference/ai-search#tag/Search-Configuration/operation/updateIndexConfigV2

Update the configuration of a single index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Request body (required)

application/json · object

Request for posting search configuration

FieldTypeRequiredDescription
indexNamestringrequiredHuman-friendly name of the index
descriptionstringoptionalDescription of the index
itemsCatalogIdstringrequiredID of the item catalog from which the index will be created
languagestringrequiredSearch language as ISO 639-1 code
enabledbooleanrequiredWhen true, the index is enabled and can be queried.
ignoreUnavailableItemsbooleanoptionalWhen true, unavailable items are not indexed, which makes the search run faster.
scoringobjectoptionalItem scoring settings that affect the presentation order of the results. 0 means the lowest importance of a parameter, 1 is the highest importance.
suggestionsobjectoptionalControls manner in which suggestions are generated
tokenizeroptionalUsed for tokenizing full text into individual words
analyzersobjectoptionalControls analyzer settings.
attributesWithoutPrefixSearcharray<string>optionalSearchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerancearray<string>optionalSearchable attributes for which typo tolerance is off
valuesWithoutTypoTolerancearray<string>optionalAttributes values for which typo tolerance is off
typoToleranceOnNumericValuesbooleanoptionalWhen true, typo tolerance is active on numbers
searchableAttributesobjectrequiredThe attributes that are taken into account as full text search terms
displayableAttributesarray<string>optionalAttributes shown in the search results
facetableAttributesobjectoptionalAttributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
filterableAttributesobjectoptionalAttributes for which filters can be used
sortableAttributesobjectoptionalAttributes using which search results can be sorted
distinctFilterAttributesobjectoptionalAttributes for which distinct can be used
recentSearchesobjectoptionalRecent searches configuration
rerankingobjectoptionalReranking configuration
geoSearchobjectoptionalGeo search configuration
queryRulesobjectoptionalConfiguration for custom behavior of query rules at the index level.

Responses

StatusDescription
200 application/jsonReturned updated configuration
500 application/jsonService not available

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"indexName":"string","description":"string","itemsCatalogId":"string","language":"string","enabled":true,"ignoreUnavailableItems":true,"scoring":{"pageVisitsPopularity":0,"transactionsPopularity":0,"personalized":0,"tieBreaker":0,"matching":{"type":"MinimumMatching","value":1},"fallbackMatching":{"type":"MinimumMatching","value":1},"similarity":{"type":"BM25","k1":1.2,"b":0.75},"crossWorkspaceMode":{"enabled":true}},"suggestions":{"smoothingModel":"Popularity","gramSize":3,"maxErrors":2,"minWordLength":4,"useAlways":false},"tokenizer":{"type":"Whitespace"},"analyzers":{"autocomplete":"Ngram"},"attributesWithoutPrefixSearch":["brand","color","promotion.type"],"attributesWithoutTypoTolerance":["itemId","link"],"valuesWithoutTypoTolerance":["Nike","blue","74997"],"typoToleranceOnNumericValues":true,"searchableAttributes":{"fullText":["brand","color","promotion.type"],"fullTextBoosted":["brand","color","promotion.type"],"fullTextStronglyBoosted":["brand","color","promotion.type"]},"displayableAttributes":["brand","color","promotion.type"],"facetableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"filterableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"sortableAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"distinctFilterAttributes":{"range":["age","customScore.value","salePrice.value"],"text":["brand","color","promotion.type"],"datetime":["created","attributes.modifiedAt"]},"recentSearches":{"windowSize":100,"timeSpan":{"type":"DAYS","value":30}},"reranking":{"dynamicReranker":{"enabled":true,"filter":"string","numberOfItems":1,"minNumberOfEvents":0},"queryClassification":{"enabled":true,"actions":[{"action":"staticFilter","minReliabilityLevel":"certain"}],"excludedPhrases":["string"],"excludedCategories":["string"]}},"geoSearch":{"geoSearchableAttribute":"string"},"queryRules":{"consequencesJoinOperators":{"standardFilters":"AND","elasticFilters":"AND"}}}'

DELETE /search/v2/indices/{indexId}/config — Delete index configuration

/api-reference/ai-search#tag/Search-Configuration/operation/deleteIndexConfigV2

Delete the configuration of a single index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_DELETE

User role permission required: assets_search: delete

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
204Configuration deleted
500 application/jsonService not available

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/state — Get index state

/api-reference/ai-search#tag/Search-Configuration/operation/getIndexStateV2

Retrieve the state of a single index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
200 application/jsonState returned
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/state \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/supported-languages — Get supported languages

/api-reference/ai-search#tag/Search-Configuration/operation/getSupportedLanguagesV2

Retrieve supported languages.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Responses

StatusDescription
200 application/jsonSupported search languages as ISO 639-1 codes
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/supported-languages \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/duplicate — Duplicate index

/api-reference/ai-search#tag/Search-Configuration/operation/duplicateIndexV2Get

duplicate index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE

User role permission required: assets_search: create

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
200 application/jsonReturned newly created duplicate index
500 application/jsonService not available

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/duplicate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Suggestions Configuration

GET /search/v2/suggestion-indices — Get suggestion indices

/api-reference/ai-search#tag/Suggestions-Configuration/operation/GetSuggestionsIndices

Retrieve a list of all suggestion index configurations in the workspace.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalName of the attribute by which the data will be sorted
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
namequerystringoptionalDeprecated parameter. If query is provided, this parameter is ignored. If an index has an id equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their name will be retrieved.
queryquerystringoptionalIf an index has an id equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their name will be retrieved. This parameter replaces the deprecated name parameter.

Responses

StatusDescription
200 application/jsonList of suggestion index configurations
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/suggestion-indices?page=4&limit=100&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&name=SOME_STRING_VALUE&query=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/suggestion-indices — Create suggestion index

/api-reference/ai-search#tag/Suggestions-Configuration/operation/PostSuggestionIndexConfig

Create a suggestion index configuration.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE

User role permission required: assets_search: create

Request body

application/json · object

FieldTypeRequiredDescription
indexNamestringrequiredName of the suggestion index
descriptionstringoptionalDescription of the suggestion index
authorintegeroptionalID of the user who created the suggestion index
enabledbooleanrequiredWhen true, index is enabled and can be queried.
sourcesobjectrequiredSources for the suggestions
denylistarray<object>optionalSuggestions that will be ignored and not shown

Responses

StatusDescription
200 application/jsonSuggestion index config created
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/suggestion-indices \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"indexName":"string","description":"string","author":0,"enabled":true,"sources":{"indices":[{"indexId":"string","minPopularity":5,"minHits":1,"minLetters":2,"daysInterval":30,"validate":false}],"external":[{"query":"string","count":0}],"generate":[{"itemsCatalogId":"string","attributes":["string"]}]},"denylist":[{"pattern":"string","matchingType":"Phrase"}]}'

GET /search/v2/suggestion-indices/{indexId}/config — Get suggestion index

/api-reference/ai-search#tag/Suggestions-Configuration/operation/GetSuggestionsIndex

Retrieve a suggestion index configuration.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
200 application/jsonSuggestion index configuration
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/suggestion-indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PUT /search/v2/suggestion-indices/{indexId}/config — Create/replace suggestion index

/api-reference/ai-search#tag/Suggestions-Configuration/operation/PutSuggestionIndexConfig

Create a suggestion index configuration or replace an existing one, given the index ID.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Request body

application/json · object

FieldTypeRequiredDescription
indexNamestringrequiredName of the suggestion index
descriptionstringoptionalDescription of the suggestion index
authorintegeroptionalID of the user who created the suggestion index
enabledbooleanrequiredWhen true, index is enabled and can be queried.
sourcesobjectrequiredSources for the suggestions
denylistarray<object>optionalSuggestions that will be ignored and not shown

Responses

StatusDescription
200 application/jsonSuggestion index config created or replaced successfully
500 application/jsonAn error occurred

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/search/v2/suggestion-indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"indexName":"string","description":"string","author":0,"enabled":true,"sources":{"indices":[{"indexId":"string","minPopularity":5,"minHits":1,"minLetters":2,"daysInterval":30,"validate":false}],"external":[{"query":"string","count":0}],"generate":[{"itemsCatalogId":"string","attributes":["string"]}]},"denylist":[{"pattern":"string","matchingType":"Phrase"}]}'

DELETE /search/v2/suggestion-indices/{indexId}/config — Delete suggestion index

/api-reference/ai-search#tag/Suggestions-Configuration/operation/DeleteSuggestionIndexConfig

Delete a suggestion index configuration.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_DELETE

User role permission required: assets_search: delete

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
204Suggestion index config deleted
500 application/jsonAn error occurred

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/search/v2/suggestion-indices/%7BindexId%7D/config \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/suggestion-indices/{indexId}/state — Get suggestion index state

/api-reference/ai-search#tag/Suggestions-Configuration/operation/GetSuggestionsIndexState

Retrieve the state of a single suggestion index.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Responses

StatusDescription
200 application/jsonSuggestion index state
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/suggestion-indices/%7BindexId%7D/state \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Query Rules

GET /search/v2/indices/{indexId}/rules — Get rules

/api-reference/ai-search#tag/Query-Rules/operation/GetRulesV2

Retrieves a list of rules.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
statusqueryenum<"finished", "draft", "paused", "scheduled", …>optionalOnly rules with this status will be retrieved.
namequerystringoptionalOnly rules containing this name will be retrieved.
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortByquerystringoptionalName of the attribute by which the data will be sorted
orderingqueryenum<"desc", "asc">optionalSorting order
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
directoryIdquerystringoptionalRequested directoryId of the rule.
searchquerystringoptionalRequested part of the name or the id of the rule.
consequenceTypequeryarray<enum<"hide", "promote", "standardFilter", "elasticFilter", …>>optionalOnly rules producing at least one of the given consequence types will be retrieved. May be repeated.

Responses

StatusDescription
200 application/jsonList of rules
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules?status=SOME_STRING_VALUE&name=SOME_STRING_VALUE&page=4&limit=100&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&directoryId=SOME_STRING_VALUE&search=SOME_STRING_VALUE&consequenceType=SOME_ARRAY_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/rules — Create rule

/api-reference/ai-search#tag/Query-Rules/operation/PostRuleV2

Creates a new rule.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_CREATE

User role permission required: assets_search: create

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index

Request body (required)

application/json · object

Request for posting a new rule or updating an existing one

FieldTypeRequiredDescription
namestringoptionalName of the rule
authorintegeroptionalThe user who created the rule
activeFromstringoptionalTime when the rules becomes active, in YYYY-MM-DD HH-MM-SS format
activeTostringoptionalTime when the rule becomes inactive, in YYYY-MM-DD HH-MM-SS format
timezonestringoptionalTimezone in UTC[+/-]X format, for example UTC+4, UTC+0, UTC-3
dataobjectoptionalThis object contains the details of what the rule does

Responses

StatusDescription
200 application/jsonID of the new rule
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string","author":0,"activeFrom":"string","activeTo":"string","timezone":"string","data":{"audience":{"segmentationIds":["34ab56cd-789be-22ee-11ab-123456789abc","12xy34z5-456b-33cc-7o52-987654321ece"]},"conditions":{"patterns":["phone","notebook","mouse {color} {brand}"],"matchingType":"is","contexts":["listing","web","mobile"],"filters":{"textFilters":{"color":{"values":["green","red"],"matchingType":"InUserFilters"}},"rangeFilters":{"price":{"ranges":[{"rightEnd":{"value":20,"inclusive":true}}],"matchingType":"Exact"}},"datetimeFilters":{"created":{"ranges":[{"rightEnd":{"value":"2024-01-01","inclusive":true}}],"matchingType":"Exact"}}}},"queryConsequences":[{"type":"removeWord","word":"string","replacement":"string"}],"postQueryConsequences":{"hideHits":["string"],"promoteHits":[{"id":"string","position":0}],"promoteHitsPositionStrategy":{"type":"custom"},"standardFilters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]},"elasticFilters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]},"boostFilters":[{"weight":-100,"filters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]}}],"topHitsFilters":[{"hitsNumber":1,"filters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]}}],"distinctFilter":{"attribute":"string","maxNumItems":0,"categoryLevelModifier":0},"sortBy":{"attribute":"string","ordering":"desc"},"customData":"{\"customLandingPage\": \"https://synerise.com/\"}","returnNoData":false,"pinFacets":[{"attribute":"size","position":1},{"attribute":"width","position":2},{"attribute":"gift_wrap"}],"hideFacets":["material","fabric","sleeve_length"]}}}'

GET /search/v2/indices/{indexId}/rules/{ruleId} — Get rule

/api-reference/ai-search#tag/Query-Rules/operation/GetRuleV2

Retrieves a rule.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_CREATE

User role permission required: assets_search: create

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
200 application/jsonQuery rule returned
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PUT /search/v2/indices/{indexId}/rules/{ruleId} — Update query rule

/api-reference/ai-search#tag/Query-Rules/operation/PutRuleV2

Updates a rule identified by id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Request body (required)

application/json · object

Request for posting a new rule or updating an existing one

FieldTypeRequiredDescription
namestringoptionalName of the rule
authorintegeroptionalThe user who created the rule
activeFromstringoptionalTime when the rules becomes active, in YYYY-MM-DD HH-MM-SS format
activeTostringoptionalTime when the rule becomes inactive, in YYYY-MM-DD HH-MM-SS format
timezonestringoptionalTimezone in UTC[+/-]X format, for example UTC+4, UTC+0, UTC-3
dataobjectoptionalThis object contains the details of what the rule does

Responses

StatusDescription
200 application/jsonQuery rule updated
500 application/jsonAn error occurred

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string","author":0,"activeFrom":"string","activeTo":"string","timezone":"string","data":{"audience":{"segmentationIds":["34ab56cd-789be-22ee-11ab-123456789abc","12xy34z5-456b-33cc-7o52-987654321ece"]},"conditions":{"patterns":["phone","notebook","mouse {color} {brand}"],"matchingType":"is","contexts":["listing","web","mobile"],"filters":{"textFilters":{"color":{"values":["green","red"],"matchingType":"InUserFilters"}},"rangeFilters":{"price":{"ranges":[{"rightEnd":{"value":20,"inclusive":true}}],"matchingType":"Exact"}},"datetimeFilters":{"created":{"ranges":[{"rightEnd":{"value":"2024-01-01","inclusive":true}}],"matchingType":"Exact"}}}},"queryConsequences":[{"type":"removeWord","word":"string","replacement":"string"}],"postQueryConsequences":{"hideHits":["string"],"promoteHits":[{"id":"string","position":0}],"promoteHitsPositionStrategy":{"type":"custom"},"standardFilters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]},"elasticFilters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]},"boostFilters":[{"weight":-100,"filters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]}}],"topHitsFilters":[{"hitsNumber":1,"filters":{"textFilters":[{"attribute":"brand","mode":"include","values":["A-Brand","B-Brand","{brand}"]}],"rangeFilters":[{"attribute":"price","operator":"gt","value":"{price}"}],"datetimeFilters":[{"attribute":"created","operator":"gt","value":"{created}"}]}}],"distinctFilter":{"attribute":"string","maxNumItems":0,"categoryLevelModifier":0},"sortBy":{"attribute":"string","ordering":"desc"},"customData":"{\"customLandingPage\": \"https://synerise.com/\"}","returnNoData":false,"pinFacets":[{"attribute":"size","position":1},{"attribute":"width","position":2},{"attribute":"gift_wrap"}],"hideFacets":["material","fabric","sleeve_length"]}}}'

DELETE /search/v2/indices/{indexId}/rules/{ruleId} — Delete rule

/api-reference/ai-search#tag/Query-Rules/operation/DeleteRuleV2

Deletes a rule identified by id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_DELETE

User role permission required: assets_search: delete

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
204Query rule deleted
500 application/jsonAn error occurred

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/rules/{ruleId}/activate — Activate rule

/api-reference/ai-search#tag/Query-Rules/operation/ActivateRuleV2

Activates a rule identified by id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
204Query rule activated
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D/activate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/rules/{ruleId}/pause — Pause rule

/api-reference/ai-search#tag/Query-Rules/operation/PauseRuleV2

Pauses a rule identified by id.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
204Query rule paused
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D/pause \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/rules/{ruleId}/draft — Draft rule

/api-reference/ai-search#tag/Query-Rules/operation/DraftRuleV2

Marks a rule as draft.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
204Query rule marked as draft
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D/draft \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /search/v2/indices/{indexId}/rules/{ruleId}/finish — Finish rule

/api-reference/ai-search#tag/Query-Rules/operation/FinishRuleV2

Marks a rule as finished. The rule becomes inactive and can never be activated again.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: QUERY_RULES_SEARCH_UPDATE

User role permission required: assets_search: update

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index
ruleIdpathintegerrequiredRule identifier

Responses

StatusDescription
204Query rule marked as finished
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/search/v2/indices/%7BindexId%7D/rules/%7BruleId%7D/finish \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Search Stats

GET /search/v2/indices/{indexId}/stats/queries/summary — Get queries stats summary

/api-reference/ai-search#tag/Search-Stats/operation/GetQueriesSummary

Retrieves the statistics of all queries or a single query defined in the request.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index for which the stats are requested
dateFromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with to, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
dateToquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
queryquerystringoptionalQuery for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchTypequeryenum<"fullTextSearch", "autocomplete", "listing", "visual", …>optionalSearch type for which stats will be retrieved.
groupByqueryenum<"date">optionalAttribute for which retrieved stats will be grouped.

Responses

StatusDescription
200 application/jsonStatistics returned
500 application/jsonService error
4xx application/jsonIncorrect request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/queries/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/stats/queries/top — Get top query statistics

/api-reference/ai-search#tag/Search-Stats/operation/GetQueriesTop

Retrieves the 1000 most popular queries.

IMPORTANT: Don't use this endpoint for displaying most popular queries to end users when they're searching. Instead, use search/v2/indices/{indexId}/list, where indexId is a suggestion index.

API consumers: Workspace (Business Profile), Synerise User, AI API key (legacy)

API key permission required: AI_STATS_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index for which the stats are requested
dateFromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with to, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
dateToquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
queryquerystringoptionalQuery for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchTypequeryenum<"fullTextSearch", "autocomplete", "listing", "visual", …>optionalSearch type for which stats will be retrieved.
queryFilterqueryenum<"queries", "queriesWithNoResults", "queriesWithUsedSuggestions">optionalQueries for which stats will be retrieved.
groupByqueryenum<"date">optionalAttribute for which retrieved stats will be grouped.
withFiltersqueryenum<true, false>optionalSwitch to display search statistics with enabled filters or without filters.
SortByqueryenum<"count", "clicks", "conversions", "clickThroughRate", …>optionalField by which results should be sorted.
orderingqueryenum<"asc", "desc">optionalSort order direction.

Responses

StatusDescription
200 application/jsonStatistics returned
500 application/jsonService error
4xx application/jsonIncorrect request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/queries/top?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&queryFilter=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&withFilters=SOME_STRING_VALUE&SortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/stats/filters/summary — Get filters stats

/api-reference/ai-search#tag/Search-Stats/operation/GetFiltersSummary

Retrieves the statistics of filters used in searches.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index for which the stats are requested
filterNamequerystringoptionalName of the filterable attribute. If present top values of this filter are returned.
dateFromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with to, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
dateToquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupByqueryenum<"date">optionalAttribute for which retrieved stats will be grouped.
orderingqueryenum<"asc", "desc">optionalSort order direction.

Responses

StatusDescription
200 application/jsonStatistics returned
500 application/jsonService error
4xx application/jsonIncorrect request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/filters/summary?filterName=brand&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/{indexId}/stats/rules/summary — Get rules stats

/api-reference/ai-search#tag/Search-Stats/operation/GetRulesSummary

Retrieves the statistics of applied rules.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdpathstringrequiredID of the index for which the stats are requested
dateFromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with to, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
dateToquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupByqueryenum<"date">optionalAttribute for which retrieved stats will be grouped.

Responses

StatusDescription
200 application/jsonStatistics returned
500 application/jsonService error
4xx application/jsonIncorrect request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /search/v2/indices/stats/queries/summary — Get queries summary for multiple indices

/api-reference/ai-search#tag/Search-Stats/operation/GetQueriesSummaryMultipleIndices

Retrieves the statistics of all queries or a single query defined in the request for multiple indices.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: assets_search: read

Parameters

NameInTypeRequiredDescription
indexIdqueryarray<string>requiredList of indices ids for which the stats are requested.
dateFromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with to, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
dateToquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
queryquerystringoptionalQuery for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchTypequeryenum<"fullTextSearch", "autocomplete", "listing", "visual", …>optionalSearch type for which stats will be retrieved.
groupByqueryenum<"date">optionalAttribute for which retrieved stats will be grouped.

Responses

StatusDescription
200 application/jsonStatistics returned
500 application/jsonService error
4xx application/jsonIncorrect request

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/stats/queries/summary?indexId=SOME_ARRAY_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Back to all API categories