AI Suite — API Reference

Analytics, recommendations, search, and more

59 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'

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'

Recommendation campaigns

GET /recommendations/v2/campaigns — Get all recommendation campaigns

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/GetRecommendationCampaignsV2

Fetch all recommendation campaigns.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_MANY_CAMPAIGN_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
pagequeryintegeroptionalPage number
limitqueryintegeroptionalMaximum number of campaigns on a page
sortByqueryenum<"createdAt", "updatedAt", "startDate", "endDate", …>optionalName of the field by which data will be sorted
orderingqueryenum<"asc", "desc">optionalSorting order
includeMetaquerybooleanoptionalIf true, a meta JSON block with pagination data is included in the response body. If false, the pagination data is included in the response headers.
typequerystringoptionalFilters the results by campaign type.
statequeryarray<enum<"draft", "active", "paused">>optionalShows only results with states matching this parameter. When this parameter is omitted, all campaigns are returned regardless of state.
searchquerystringoptionalSearches campaigns by the specified phrase in their id and title.

Responses

StatusDescription
200 application/jsonReturns paginated campaigns. If showMeta was set to true, the metadata is included in the JSON response. If it was set to false, the metadata is included in the headers.
404 application/jsonCould not find campaigns
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/campaigns?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&type=SOME_STRING_VALUE&state=SOME_ARRAY_VALUE&search=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/campaigns — Create a recommendation campaign

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/CreateRecommendationCampaignV2

Create a new recommendation campaign.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_CAMPAIGN_CREATE

User role permission required: campaigns_recommendations: create

Request body (required)

application/json · object

All the details of a campaign

Responses

StatusDescription
200 application/jsonOK campaign has been returned
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/campaigns \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"similar","parameters":{"additionalResponseAttributes":["string"],"boostMetric":"string","sortMetric":"string","boostMetricStrength":-100,"shuffleNumItems":0,"personalizedBoostingStrength":0},"title":"string","slug":"string","description":"string","startDate":"string","endDate":"string","state":"draft","filterRules":{"excludePurchasedItems":true,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":true,"elasticExcludePurchasedItemsSinceDays":0},"itemsCatalogId":"string","slots":[{"name":"string","itemMin":0,"itemMax":0,"filterRules":{"filters":"string","elasticFilters":"string"},"distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]},"attribute":{"name":"string","levelRangeModifier":0},"numRows":0,"numItems":0,"useDefaultDistinctFilters":true,"useDefaultItemFilters":true}],"keepSlotsOrder":true,"personalizeSlotsOrder":false,"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"itemsSource":{"type":"aggregate","id":"string"}}'

GET /recommendations/v2/campaigns/{campaignId} — Get recommendation campaign details

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/GetRecommendationCampaignV2

Retrieve the details of a single campaign.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_SINGLE_CAMPAIGN_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the campaign

Responses

StatusDescription
200 application/jsonData of a single campaign
404 application/jsonCould not find campaign
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/campaigns/{campaignId} — Update a recommendation campaign

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/UpdateRecommendationCampaignV2

Update a recommendation campaign by changing the parameters or copying the definition from another campaign.

When you copy from another campaign:

  • the following campaign data is NOT updated:
    • title
    • state
    • start_date
    • end_date
    • campaignId
    • createdAt
  • modified_by_user_id changes to the user who performed the update

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_CAMPAIGN_UPDATE

User role permission required: campaigns_recommendations: update

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the campaign

Request body (required)

application/json · recommendation-campaigns-RecommendationCampaignUpdateRequest

Definition of the updated campaign.

FieldTypeRequiredDescription
copyConfigurationFromstringrequiredSource campaign ID. When you copy from another campaign: the following campaign data is NOT updated: title state start_date end_date campaignId createdAt modified_by_user_id changes to the user who performed the update

Responses

StatusDescription
200 application/jsonCampaign updated and returned
404 application/jsonCould not find campaign
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"type":"similar","parameters":{"additionalResponseAttributes":["string"],"boostMetric":"string","sortMetric":"string","boostMetricStrength":-100,"shuffleNumItems":0},"campaignId":"string","title":"string","slug":"string","description":"string","startDate":"string","endDate":"string","createdAt":"string","updatedAt":"string","state":"draft","filterRules":{"excludePurchasedItems":true,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":true,"elasticExcludePurchasedItemsSinceDays":0},"itemsCatalogId":"string","additionalResponseAttributes":["string"],"slots":[{"name":"string","itemMin":0,"itemMax":0,"filterRules":{"filters":"string","elasticFilters":"string"},"distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]},"attribute":{"name":"string","levelRangeModifier":0},"numRows":0,"numItems":0,"useDefaultDistinctFilters":true,"useDefaultItemFilters":true}],"keepSlotsOrder":true,"personalizeSlotsOrder":false,"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"itemsSource":{"type":"aggregate","id":"string"},"abTest":{"experimentId":0,"variantId":0,"status":"NotStarted","isBaseline":true},"crossWorkspaceMode":{"enabled":true}}'

DELETE /recommendations/v2/campaigns/{campaignId} — Delete a recommendation campaign

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/DeleteRecommendationCampaign

Delete a recommendation campaign. This operation is irreversible.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_CAMPAIGN_DELETE

User role permission required: campaigns_recommendations: delete

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the campaign

Responses

StatusDescription
200 application/jsonOK campaign has been deleted
404 application/jsonCould not find campaign
500 application/jsonAn error occurred

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/campaigns/state — Change campaigns' states

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/UpdateRecommendationsStatesV2

Change the status of one or more campaigns.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_STATE_CAMPAIGN_UPDATE

User role permission required: campaigns_recommendations: update

Request body (required)

application/json · recommendation-campaigns-RecommendationStateChangeRequestV2

List of updated campaign IDs and new states.

FieldTypeRequiredDescription
stateenum<"draft", "active", "paused", "deleted">requiredCampaign status
idsarray<string>requiredAn array of campaign IDs.

Responses

StatusDescription
200 application/jsonCampaigns status changed
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/campaigns/state \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"state":"draft","ids":["string"]}'

POST /recommendations/v2/campaigns/{campaignId}/copy — Copy a recommendation campaign

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/CopyRecommendationCampaignV2

Copy a campaign. The copied campaign's state will be draft and slug will be undefined.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_COPY_CAMPAIGN_CREATE

User role permission required: campaigns_recommendations: create

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the campaign

Responses

StatusDescription
200 application/jsonCopy created and returned
404 application/jsonCould not find campaign
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D/copy \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /recommendations/v2/campaigns/simplified — Get simplified recommendation campaigns

/api-reference/ai-recommendations#tag/Recommendation-campaigns/operation/GetSimplifiedRecommendationCampaign

Fetch simplified recommendation campaign data.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: RECOMMENDATIONS_V2_MANY_SIMPLIFIED_CAMPAIGN_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
typequeryarray<string>optionalFilter by campaign type.
statequeryarray<enum<"draft", "active", "paused">>optionalFilter by states.

Responses

StatusDescription
200 application/jsonSimplified campaigns returned
404 application/jsonCould not find campaign
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/campaigns/simplified?type=SOME_ARRAY_VALUE&state=SOME_ARRAY_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Recommendation statistics

POST /recommendations/v2/campaigns/stats — Get recommendation campaign statistics

/api-reference/ai-recommendations#tag/Recommendation-statistics/operation/PostCampaignsStats

Retrieves the statistics of campaigns defined in the request.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: campaigns_recommendations: read

Request body (required)

application/json · object

Request for recommendation campaigns stats.

FieldTypeRequiredDescription
campaignIdsarray<string>requiredList of campaign IDs for which the statistics are requested. Must not be empty.
fromstringoptionalUpper 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.
tostringoptionalLower bound of the interval for which the statistics will be retrieved.Must be provided with from, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
timeZonestringoptionalTime zone identifier.

Responses

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

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/campaigns/stats \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignIds":["string"],"from":"2019-08-24","to":"2019-08-24","timeZone":"Europe/Warsaw"}'

GET /recommendations/v2/campaigns/stats/global — Get global recommendation campaign statistics

/api-reference/ai-recommendations#tag/Recommendation-statistics/operation/GetCampaignsGlobalStats

Retrieves the statistics of all recommendation campaigns.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
fromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with from, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
toquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
timeZonequerystringoptionalTime zone identifier.

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/recommendations/v2/campaigns/stats/global?from=SOME_STRING_VALUE&to=SOME_STRING_VALUE&timeZone=Europe%2FWarsaw' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /recommendations/v2/campaigns/{campaignId}/stats — Get recommendation campaign statistics

/api-reference/ai-recommendations#tag/Recommendation-statistics/operation/GetCampaignStats

Retrieves the statistics of a single recommendation campaign.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the recommendation campaign
fromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with from, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
toquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
timeZonequerystringoptionalTime zone identifier.

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/recommendations/v2/campaigns/50NCGoRK0VRb/stats?from=SOME_STRING_VALUE&to=SOME_STRING_VALUE&timeZone=Europe%2FWarsaw' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /recommendations/v2/campaigns/{campaignId}/products/stats — Get statistics for top items in a campaign

/api-reference/ai-recommendations#tag/Recommendation-statistics/operation/GetRecoTopProductsStats

Retrieves the statistics of top products for a single recommendation campaign.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_STATS_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
campaignIdpathstringrequiredID of the recommendation campaign
fromquerystringoptionalUpper bound of the interval for which the statistics will be retrieved.Must be provided with from, otherwise the filter is treated as unspecified.If not specified, the interval is last 7 days.
toquerystringoptionalLower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
timeZonequerystringoptionalTime zone identifier.
metricqueryenum<"views", "clicks", "revenue", "generations", …>optionalThe response will include statistics for up to 10 top-performing items according to the selected metric, sorted from best to worst. If not specified, the default metric is views. views - the number of displayed recommendation frames. generations - the number of generated recommendation frames. clicks - the number of times an item in a recommendation frame was clicked. charges - the number of transactions caused by the recommendation. revenue - the revenue generated by the recommendation.

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/recommendations/v2/campaigns/50NCGoRK0VRb/products/stats?from=SOME_STRING_VALUE&to=SOME_STRING_VALUE&timeZone=Europe%2FWarsaw&metric=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Recommendations

GET /recommendations/v2/recommend/campaigns/{campaignIdentifier} — Get recommendations by campaign

/api-reference/ai-recommendations#tag/Recommendations/operation/GetRecommendationsByCampaignV2

This method allows you to retrieve recommendations based on a campaignID or a slug and a context. The context is built based on:

  • campaign identifier (required)
  • profile UUID
  • items (for example, items currently in the basket)
  • item exclusions

This is the recommended and simplest way to fetch recommendations.

Before you use this method, you must to create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

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

API key permission required: API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
campaignIdentifierpathstringrequiredRecommendation campaign identifier - a campaignID or a slug
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemIdquerystringoptionalItem ID or item IDs for the recommendation context. This parameter is: required for similar/complementary items campaigns. optional for personalized campaigns. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. You can repeat this parameter in order to pass a number of context-creating items, for example, in a cart recommendation campaign. This overrides the itemsSource settings of the campaign definition. Alternatively, you can pass the itemsSourceType and itemsSourceId parameters to use context items from source (aggregate or expression). These parameters can't be used at the same request with itemId.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
itemsSourceTypequeryenum<"aggregate", "expression">optionalItem ID or item IDs source type for the recommendation context. Must be used with itemSourceId. This overrides the itemsSource settings of the campaign definition. In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters. If the items' source type is 'aggregate', the aggregate result will be used as context items. If the items' source type is 'expression', the expression result will be used as context items. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the itemId parameter to define context items directly. Only one of these options is allowed at the same time.
itemsSourceIdquerystringoptionalSource of item IDs for the recommendation context. In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters. Must be used with itemsSourceType. If the items' source type is 'aggregate', this is the aggregate's ID. If the items' source type is 'expression', this is the expression's ID. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the itemId parameter to define context items directly. Only one of these options is allowed at the same time.
externalItemIdquerystringoptionalItems provided by an external recommendation model to be returned as recommendation results. You can repeat this parameter to pass multiple external items. This parameter is used with campaigns of type "external-items".
itemIdExcludedquerystringoptionalIDs of items that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFiltersquerystringoptional IMPORTANT: The filtersJoiner attribute is REQUIRED when additionalFilters is included. If filtersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in filtersJoiner. This parameter must include all the additional filters as a single string, for example additionalFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
filtersJoinerqueryenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalFilters with the campaign's existing filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
additionalElasticFiltersquerystringoptional IMPORTANT: The elasticFiltersJoiner attribute is REQUIRED when additionalElasticFilters is included. If elasticFiltersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in elasticFiltersJoiner. This parameter must include all the additional filters as a single string, for example additionalElasticFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
elasticFiltersJoinerqueryenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalElasticFilters with the campaign's existing elastic filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
displayAttributequerystringoptionalItem attribute whose value will be returned in the recommendation response. The parameter value will be merged with the configuration of the recommendation. This parameter can be passed multiple times.
includeContextItemsquerybooleanoptionalWhen true, the recommendation response will include context items metadata.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated 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/jsonRecommendations for the provided context. The response schema depends on your Workspace configuration. The schema below only includes the static elements.
404 application/jsonNo recommendations could be generated for the specified campaign and context.
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&inventoryChannelId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&externalItemId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=effectivePrice%3E300%20AND%20effectivePrice%3C400&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/campaigns — Get recommendations by campaign

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendationsByCampaignV2

This method allows you to retrieve recommendations based on a campaignID or slug and a context. The context is built based on:

  • campaign ID or slug (one of those is required)
  • profile UUID
  • items (for example, items currently in the basket)
  • item exclusions

This is the recommended and simplest way to fetch recommendations.

Before you use this method, you must to create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

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

API key permission required: API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_READ

Request body

application/json · recommendations-api-materializer-PostRecommendationsRequest

FieldTypeRequiredDescription
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
campaignIdstringoptionalRecommendation campaign ID for establishing the context
slugstringoptionalRecommendation campaign slug for establishing the context
itemsarray<string>optionalAn array of item identifiers (itemId in the item feed) for the context. This could be, for example, the current basket, or the item that is currently being viewed. This overrides the itemsSource settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. Alternatively, you can use the itemsSource object to get item IDs from an aggregate or expression. items and itemsSource can't be used at the same time.
itemsSourceobjectoptionalSource of the Item ID or item IDs for the recommendation context. This overrides the itemsSource settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the itemId parameter to define context items directly. Only one of these options is allowed at the same time.
itemsExcludedarray<string>optionalItems (identified by itemId in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFiltersstringoptional IMPORTANT: The filtersJoiner attribute is REQUIRED when additionalFilters is included. If filtersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in filtersJoiner. This parameter must include all the additional filters as a single string, for example additionalFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
filtersJoinerenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalFilters with the campaign's existing filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
additionalElasticFiltersstringoptional IMPORTANT: The elasticFiltersJoiner attribute is REQUIRED when additionalElasticFilters is included. If elasticFiltersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in elasticFiltersJoiner. This parameter must include all the additional filters as a single string, for example additionalElasticFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
elasticFiltersJoinerenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalElasticFilters with the campaign's existing elastic filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
displayAttributesarray<string>optionalAn array of item attributes which value will be returned in a recommendation response. The array will be merged together with the configuration of the recommendation.
includeContextItemsbooleanoptionalWhen true, the recommendation response will include context items metadata.
recommendedItemsFromExternalModelarray<array<string>>optionalItems provided by an external recommendation model to be returned as recommendation results. This parameter is used with campaigns of type "external-items".
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.

Responses

StatusDescription
200 application/jsonRecommendations for the provided context. The response schema depends on your Workspace configuration. The schema below only includes the static elements.
404 application/jsonNo recommendations could be generated for the specified campaign and context.
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/campaigns \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"clientUUID":"string","campaignId":"string","slug":"string","items":["string"],"itemsSource":{"type":"aggregate","id":"string"},"itemsExcluded":["string"],"additionalFilters":"effectivePrice>300 AND effectivePrice<400","filtersJoiner":"AND","additionalElasticFilters":"effectivePrice>300 AND effectivePrice<400","elasticFiltersJoiner":"AND","displayAttributes":["string"],"includeContextItems":true,"recommendedItemsFromExternalModel":[["string"]],"inventoryContext":{"channelIds":["string"]},"params":{"source":"mobile"}}'

POST /recommendations/v2/recommend/campaigns/{campaignIdentifier}/by/{identifierName} — Get recommendations by campaign and profile identifier

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendationsByCampaignAndidentifierNameV2

Before you use this method: you must create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

The method allows you to retrieve recommendations based on a campaignID or a slug, profile's identifier name (the value of the identifier is provided in the request body), and a context. The context is built based on:

  • campaign identifier (required)
  • identifierName (required)
  • identifierValue (required)
  • items (for example, items currently in the basket)
  • item exclusions

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_MATERIALIZER_V2_RECOMMEND_WITH_CUSTOM_ID_RECOMMENDATIONS_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
campaignIdentifierpathstringrequiredRecommendation campaign identifier - a campaignID or a slug
identifierNamepathenum<"id", "uuid", "email", "custom_identify">requiredThe name of the profile identifier to use for the request. By default, the allowed identifier types are id, uuid, email, and custom_identify. This may be changed in the workspace configuration.

Request body

application/json · recommendations-api-materializer-PostRecommendationsWithIdentifierValueRequest

FieldTypeRequiredDescription
identifierValuestringrequiredValue of the identifier selected in the path attributes
itemsarray<string>optionalAn array of item identifiers (itemId in the item feed) for the context. This could be, for example, the current basket, or the item that is currently being viewed. This overrides the itemsSource settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. Alternatively, you can use the itemsSource object to get item IDs from an aggregate or expression. items and itemsSource can't be used at the same time.
itemsSourceobjectoptionalSource of the Item ID or item IDs for the recommendation context. This overrides the itemsSource settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the itemId parameter to define context items directly. Only one of these options is allowed at the same time.
itemsExcludedarray<string>optionalItems (identified by itemId in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFiltersstringoptional IMPORTANT: The filtersJoiner attribute is REQUIRED when additionalFilters is included. If filtersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in filtersJoiner. This parameter must include all the additional filters as a single string, for example additionalFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
filtersJoinerenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalFilters with the campaign's existing filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
additionalElasticFiltersstringoptional IMPORTANT: The elasticFiltersJoiner attribute is REQUIRED when additionalElasticFilters is included. If elasticFiltersJoiner is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in elasticFiltersJoiner. This parameter must include all the additional filters as a single string, for example additionalElasticFilters=effectivePrice>300 AND effectivePrice<400 (the spaces are required).
elasticFiltersJoinerenum<"AND", "OR", "REPLACE">optionalDefines the logic of merging additionalElasticFilters with the campaign's existing elastic filters. REPLACE replaces the campaign's filters with your filters. AND matches if both your filters and the campaign filters are met. OR matches if at least one of the filters is met.
displayAttributesarray<string>optionalAn array of item attributes which value will be returned in a recommendation response. The array will be merged together with the configuration of the recommendation.
includeContextItemsbooleanoptionalWhen true, the recommendation response will include context items metadata.
recommendedItemsFromExternalModelarray<array<string>>optionalItems provided by an external recommendation model to be returned as recommendation results. This parameter is used with campaigns of type "external-items".
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.

Responses

StatusDescription
200 application/jsonRecommendations for the provided context. The response schema depends on your Workspace configuration. The schema below only includes the static elements.
404 application/jsonNo recommendations could be generated for the specified campaign and context.
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignIdentifier%7D/by/%7BidentifierName%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string","items":["string"],"itemsSource":{"type":"aggregate","id":"string"},"itemsExcluded":["string"],"additionalFilters":"effectivePrice>300 AND effectivePrice<400","filtersJoiner":"AND","additionalElasticFilters":"effectivePrice>300 AND effectivePrice<400","elasticFiltersJoiner":"AND","displayAttributes":["string"],"includeContextItems":true,"recommendedItemsFromExternalModel":[["string"]],"inventoryContext":{"channelIds":["string"]},"params":{"source":"mobile"}}'

POST /recommendations/v2/recommend/campaigns/preview — Preview campaign recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostPreviewRecommendations

This method allows you to preview recommendations for a campaign with a given configuration before creating it.

Note: This method is not an alternative to creating recommendations for an existing campaign. It is intended for testing purposes only.

The recommendation context is built based on:

  • profile UUID
  • items
  • item exclusions

API consumers: Workspace (Business Profile), Synerise User

API key permission required: API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_PREVIEW_READ

User role permission required: campaigns_recommendations: read

Request body

application/json · object

FieldTypeRequiredDescription
clientUUIDstringoptionalUUID of the client
itemsarray<recommendations-api-materializer-Item>optionalA list of itemIds for building the context. Alternatively, you can use the itemsSource parameter to provide the context. Item context is required by these recommendation types: similar, cross-sell, set-complement, visually-similar, item-comparison. In other recommendation types, the item context is optional, but may be used by the model when scoring items.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).

Responses

StatusDescription
200 application/jsonRecommendations for the provided context. The response schema depends on your Workspace configuration. The schema below only includes the static elements.
404 application/jsonNo recommendations could be generated for the specified campaign and context.
429 application/jsonThe user has sent too many requests in a given amount of time ("rate limiting").
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/campaigns/preview \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"clientUUID":"50829d26-5337-410e-9365-b40f7a01bb61","items":["string"],"includeContextItems":false,"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"type":"similar","parameters":{"additionalResponseAttributes":["string"],"boostMetric":"string","sortMetric":"string","boostMetricStrength":-100,"shuffleNumItems":0,"personalizedBoostingStrength":0},"title":"preview","campaignId":"preview","filterRules":{"excludePurchasedItems":true,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":true,"elasticExcludePurchasedItemsSinceDays":0},"itemsCatalogId":"string","slots":[{"name":"string","itemMin":0,"itemMax":0,"filterRules":{"filters":"string","elasticFilters":"string"},"distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]},"attribute":{"name":"string","levelRangeModifier":0},"numRows":0,"numItems":0}],"keepSlotsOrder":true,"personalizeSlotsOrder":false,"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"itemsSource":{"type":"aggregate","id":"string"}}'

GET /recommendations/v2/recommend/items/users/{clientUuid} — Personalized recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/RecommendForUserV2

Retrieve item recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_PERSONALIZED_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredRecommendations will be generated for the provided profile UUID.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemIdquerystringoptionalItem identifier, equal to itemId from the item feed. It can be used to define the item context of the query.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonPersonalized recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/users/{clientUuid} — Personalized recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendForUserV2

Retrieve item recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_PERSONALIZED_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredRecommendations will be generated for the provided profile UUID.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonPersonalized recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

POST /recommendations/v2/recommend/items/users/{clientUuid}/sections — Section recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendSectionsForUserV2

Retrieve item recommendations grouped by attribute.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_SECTION_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.

Request body (required)

application/json · recommendations-rust-all-SectionsSlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
metadataCatalogIdstringoptionalID of the catalog which stores attribute metadata
slotsarray<recommendations-rust-all-SectionSlotSchemaV2>requiredSlots data

Responses

StatusDescription
200 application/jsonSection recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/sections \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"metadataCatalogId":"string","slots":[{"name":"string","attribute":{"name":"string","levelRangeModifier":0},"numRows":1,"numItems":1,"filters":"string","elasticFilters":"string"}]}'

POST /recommendations/v2/recommend/items/users/{clientUuid}/attributes — Attribute recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendAttributesForUserV2

Retrieve attribute recommendations.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_ATTRIBUTE_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.

Request body (required)

application/json · recommendations-rust-all-AttributesSlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
metadataCatalogIdstringoptionalID of the catalog which stores attribute metadata
slotsarray<recommendations-rust-all-AttributeSlotSchemaV2>requiredSlots data

Responses

StatusDescription
200 application/jsonAttribute recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/attributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"metadataCatalogId":"string","slots":[{"name":"string","attribute":{"name":"string","levelRangeModifier":0},"minNumItems":1,"maxNumItems":5,"filters":"string","elasticFilters":"string"}]}'

GET /recommendations/v2/recommend/items/users/{clientUuid}/last — Last viewed recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/RecommendLastViewedForUserItems

Retrieve recent item recommendations seen by a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_LAST_VIEWED_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonLast viewed recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/last?campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/users/{clientUuid}/last — Last viewed recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendLastViewedForUserItems

Retrieve recent item recommendations seen by a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_LAST_VIEWED_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonLast viewed recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/last \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/users/{clientUuid}/aggregates/{aggregateUUID} — Recent interactions recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/GetRecommendRecentInteractions

Retrieve recent interactions recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_RECENT_INTERACTIONS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.
aggregateUUIDpathstringrequiredInformation will be shown for the provided aggregate UUID.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonRecent interactions recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/aggregates/%7BaggregateUUID%7D?campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/users/{clientUuid}/aggregates/{aggregateUUID} — Recent interactions recommendations

/api-reference/ai-recommendations#tag/Recommendations/operation/PostRecommendRecentInteractions

Retrieve recent interactions recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_RECENT_INTERACTIONS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredInformation will be shown for the provided profile UUID.
aggregateUUIDpathstringrequiredInformation will be shown for the provided aggregate UUID.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonRecent interactions recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/users/%7BclientUuid%7D/aggregates/%7BaggregateUUID%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/metric — Scoring by metric

/api-reference/ai-recommendations#tag/Recommendations/operation/GetItemsByMetric

Returns items with the highest score of a chosen metric. A list of available metrics can be checked by using this endpoint.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_METRICS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
sortMetricquerystringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemIdquerystringoptionalItem identifier, equal to itemId from the item feed. It can be used to define the item context of the query.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonItems with the highest metric scores
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/metric?sortMetric=SOME_STRING_VALUE&minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/metric — Scoring by metric

/api-reference/ai-recommendations#tag/Recommendations/operation/PostItemsByMetric

Returns items with the highest score of a chosen metric. A list of available metrics can be checked by using this endpoint.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_METRICS_RECOMMENDATIONS_READ

Request body (required)

application/json · recommendations-rust-all-MetricsBodySchemaV2

Definition of the requested recommendation

Responses

StatusDescription
200 application/jsonItems with the highest metric scores
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/metric \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/complementary — Complementary items for a cart

/api-reference/ai-recommendations#tag/Recommendations/operation/ComplementItems

Show recommendations based on the contents of a cart.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemIdqueryarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
boostMetricquerystringoptionalID of the metric to boost the results by. Metric scores will be combined with recommendation scores, favoring the best-performing results. The list of available metrics can be checked by using this endpoint.
sortMetricquerystringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonCart complementary recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/complementary?clientUUID=SOME_STRING_VALUE&minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemId=SOME_ARRAY_VALUE&itemCatalogId=SOME_STRING_VALUE&boostMetric=SOME_STRING_VALUE&sortMetric=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/complementary — Complementary items for a cart

/api-reference/ai-recommendations#tag/Recommendations/operation/PostComplementItems

Show recommendations based on the contents of a cart.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_RECOMMENDATIONS_READ

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonCart complementary recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/complementary \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/{itemId}/complementary — Complementary items

/api-reference/ai-recommendations#tag/Recommendations/operation/GetComplementaryItems

Returns items complementary to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_PRODUCTS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonItems complementary to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/complementary?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/{itemId}/complementary — Complementary items

/api-reference/ai-recommendations#tag/Recommendations/operation/PostComplementaryItems

Returns items complementary to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_PRODUCTS_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonItems complementary to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/complementary \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/{itemId}/similar — Similar items

/api-reference/ai-recommendations#tag/Recommendations/operation/GetSimilarItems

Returns items similar to a given item.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_SIMILAR_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonItems similar to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/{itemId}/similar — Similar items

/api-reference/ai-recommendations#tag/Recommendations/operation/PostSimilarItems

Returns items similar to a given item.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_SIMILAR_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonItems similar to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/{itemId}/similar/visual — Visually similar

/api-reference/ai-recommendations#tag/Recommendations/operation/GetSimilarVisualItems

Returns items visually similar to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_VISUAL_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated event. They must be in the name:value format. The total size must not exceed 500 bytes when written as a JSON object.
inventoryChannelIdquerystringoptionalInventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
crossWorkspaceModequerybooleanoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.

Responses

StatusDescription
200 application/jsonItems visually similar to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar/visual?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/{itemId}/similar/visual — Visually similar

/api-reference/ai-recommendations#tag/Recommendations/operation/PostSimilarVisualItems

Returns items visually similar to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_VISUAL_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
itemIdpathstringrequiredItem identifier, equal to itemId from the item feed.

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonItems visually similar to the given item
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar/visual \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

GET /recommendations/v2/recommend/items/next-interaction — Next interaction

/api-reference/ai-recommendations#tag/Recommendations/operation/NextInteractionRecommendation

The "next interaction" model recommends items that are most likely to produce a page.visit or product.buy event.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_NEXT_INTERACTION_RECOMMENDATIONS_READ

Parameters

NameInTypeRequiredDescription
clientUUIDquerystringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
minNumItemsqueryintegeroptionalThe minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItemsqueryintegeroptionalThe maximal number of returned item recommendations.
campaignIdquerystringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamequerystringoptionalThe campaign name which will be included in the recommendation.generated event.
excludePurchasedItemsquerybooleanoptionalWhen true, the recommendation results will include only items that the profile hasn't purchased before.IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDaysqueryintegeroptionalLimits the application of the excludePurchasedItems filter to a specified number of days.
filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filtersquerystringoptionalThis string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemIdqueryarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
itemCatalogIdquerystringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
boostMetricquerystringoptionalID of the metric to boost the results by. Metric scores will be combined with recommendation scores, favoring the best-performing results. The list of available metrics can be checked by using this endpoint.
sortMetricquerystringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
distinctFilterqueryobjectoptional
includeContextItemsquerybooleanoptionalThe recommendation results will include context items from the request.
paramsqueryarray<string>optionalList of extra params that will be added to the recommendation.generated 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/jsonNext interaction recommendation
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/recommendations/v2/recommend/items/next-interaction?clientUUID=SOME_STRING_VALUE&minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemId=SOME_ARRAY_VALUE&itemCatalogId=SOME_STRING_VALUE&boostMetric=SOME_STRING_VALUE&sortMetric=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /recommendations/v2/recommend/items/next-interaction — Next interaction

/api-reference/ai-recommendations#tag/Recommendations/operation/PostNextInteractionRecommendation

The "next interaction" model recommends items that are most likely to produce a page.visit or product.buy event.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities in the item feed.

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

API key permission required: RECOMMENDATIONS_V2_NEXT_INTERACTION_RECOMMENDATIONS_READ

Request body (required)

application/json · recommendations-rust-all-SlotsBodySchemaV2

Definition of the requested recommendation

FieldTypeRequiredDescription
campaignIdstringoptionalThe campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignNamestringoptionalThe campaign name which will be included in the recommendation.generated event.
catalogIdstringoptionalID (not name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
clientUUIDstringoptionalProfile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIdsarray<string>optionalItem identifiers, equal to itemId from the item feed. They can be used to define the item context of the query.
includeContextItemsbooleanoptionalThe recommendation results will include context items from the request.
filterRulesobjectoptionalFilter configuration
displayAttributesstringoptionalAttributes to be returned
abTestContextobjectoptionalA/B test context.
paramsobjectoptionalExtra parameters that will be added to the recommendation.generated event. The total size must not exceed 500 bytes.
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
keepSlotsOrderbooleanoptional When true, the data array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in data are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When false, the data array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional extras.slots object always shows slots and items as if this setting was true. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
personalizeSlotsOrderbooleanoptionalSort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set personalizeSlotsOrder to true, keepSlotsOrder must also be true.
sortMetricstringoptionalID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
boostingParametersobjectoptionalResult boosting parameters
boostingStrategiesarray<recommendations-rust-all-BoostingStrategyV2>optionalBoosting strategies
crossWorkspaceModeobjectoptionalSpecifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
slotsarray<recommendations-rust-all-SlotSchemaV2Rust>requiredSlot definitions. To apply default values and fetch all the results as a single slot, send slots as an array with one empty object.

Responses

StatusDescription
200 application/jsonNext interaction recommendations
404 application/jsonNo recommendations could be generated for the specified profile and filters
500 application/jsonAn error occurred

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/recommendations/v2/recommend/items/next-interaction \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'

Time Optimizer

POST /activity-time-estimator/v1/query-model — Generate activity time predictions

/api-reference/ai-suite#tag/Time-Optimizer/operation/generate-time-predictions

Calculate the probability of a profile performing an activity (event) at specific times of the week.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: AI_TIME_OPTIMIZER_GET_PREDICTIONS_ANALYTICS_READ

User role permission required: analytics_ai_time_optimizer: read

Request body

application/json · object

FieldTypeRequiredDescription
clientIDarray<string>requiredAn array of profile IDs. To generate predictions for fake profiles, send empty strings as the identifiers.
modestringoptionalThe mode name
timeIndexarray<any>optionalAn array of times and time ranges to include in the predictions. If empty or omitted, the entire week is included (with the exceptions listed in timeIndexExclude, if they exist). A time range is a two-item array. For example, [4,7] is the range from Monday, 03:00 to Monday, 06:59. You can mix hours and time ranges in the request.
timeIndexExcludearray<any>optionalAn array of times and time ranges to exclude from the predictions. If empty or omitted, the entire week is included (according to the time selections made in timeIndex, if they exist). A time range is a two-item array. For example, [4,7] is the range from Monday, 03:00 to Monday, 06:59. You can mix hours and time ranges in the request.
topNintegeroptionalThe number of best predictions to return for each profile. If omitted, predictions for every hour of the week are returned.
clientUUIDarray<string>requiredAn array of profile UUIDs. To generate predictions for fake profiles, send empty strings as the identifiers.

Responses

StatusDescription
200 application/jsonPredicted activity times

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/activity-time-estimator/v1/query-model \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"clientID":["67346"],"mode":"standard","timeIndex":[[0,23],24,25,26,[27,48]],"timeIndexExclude":[[0,23],24,25,26],"topN":1}'

Item filters

POST /items/v2/filter/validate — Validate item filter

/api-reference/ai-suite#tag/Item-filters/operation/ValidateItemFilter

This endpoint lets you validate the syntax of a filter and preview its results.

The parserResult object in the response validates only the IQL syntax, it does not check if the attributes or contexts referenced in the IQL query exist!

API consumers: Workspace (Business Profile), Synerise User

API key permission required: ITEMS_FILTER_VALIDATE_READ

User role permission required: campaigns_recommendations: read

Parameters

NameInTypeRequiredDescription
itemsCatalogIdquerystringoptionalID of the item catalog that contains the items tested in the request. If not provided, "default" is assumed - however, the "default" catalog may not exist in your workspace. NOTE: This ID is available in the details the search index or recommendation campaign you want to make test requests for.
exampleItemsqueryintegeroptionalControls how many example items will be returned

Request body

application/json · items-filter-all-ValidateItemsFilterRequestBody

FieldTypeRequiredDescription
filteringStringstringrequiredIQL filtering expression
clientUUIDstringoptionalUUID of the profile which creates the profile context
contextItemsarray<string>optionalitemIds of the items which create the item context
inventoryContextoptionalInventory context used to evaluate inventory-related filters and boosting strategies. Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
candidateItemsarray<string>optionalArray of itemIds that will be tested against the IQL expression. You can use this with test items to verify that the query matches the items you expected.

Responses

StatusDescription
200 application/jsonValidation response
400 application/jsonBad Request
500 application/jsonService not available
502 application/jsonCatalog not ready

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"filteringString":"IF(\"abcd\" IN client.tags,discount == 0,discount > 0)","clientUUID":"68df2317-0edb-4cc9-8b39-5ab68325f891","contextItems":["12345"],"inventoryContext":{"channelIds":["string"]},"candidateItems":["67890"]}'

Back to all API categories