AI Search (Apr 18, 2024 4:05:18 PM)

Download OpenAPI specification:Download

Welcome to Synerise API Reference! We hope that you'll enjoy your stay here.

If you need help with our services, feel free to contact us at support@synerise.com.

Authentication

JWT

Synerise uses JSON Web Token (JWT) as the authorization method. The token is generated by the auth/login endpoint. You need to include it in the Authorization header of your requests, with a Bearer prefix. See this simplified example of a call:

curl -X GET https://api.synerise.com/v4/clients \
-H 'Accept: application/json' \
-H 'Api-Version: 4.4' \
-H 'Authorization: Bearer eyJhbGciOiJSzZXIiLCJjdGQiOjE1NTI0NjMzMjg4NjIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsIm5tZSI' \
-H 'Content-Type: application/json'

Remember to include a space between Bearer and the token.

The token is valid for one hour (unless configured differently). You can request a refreshed key for the session by using the auth/refresh endpoint before the current token expires.

You can verify your JWT signature by using the public key.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

TrackerKey

Authorization by tracker key sent in a token query parameter. This may be the same key as used in the tracking code of the website. For details, see this article: https://help.synerise.com/developers/web/installation-and-configuration/#creating-a-tracking-code.

Security Scheme Type	API Key
Query parameter name:	token

Authorization

Methods to authorize and obtain JWT token required by our API endpoints

Refresh a Profile token

Retrieve a refreshed JWT Token to prolong the session.

The current token must still be active at the time of the request.

API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client)
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey

required

string

Profile API key

Responses

Request samples

Content type

application/json

{"apiKey": "string"
}

Response samples

200
401

Content type

application/json

{"token": "eyJhbGciOiinvalidI6IkFQSSIsInJsbSI6ImNsaWVudCIsImN0ZCI6MTUyODM1NTgzMjEzOCwiZW1sIjoia3J6eXN6dG9mLmN6ZXJlcGFrQGdtYWlsLmNvbSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo1OTQsImNsSWQiOjUyNTQ0NjU3NCwinvalidx2XwJp-QBZ94d_EEKf41KtDCE33KhP_vTAYrs-JzbnIHgKRvG6ZRwsNOL8OTnbfbUZH4XYaqBB_tZTPPKfzHutP6GEGp7PLtu2E92JbChkVyrn8VCQ5v4z2e1-zsdgbmWcQk2g9RydaydO6NYO55suT3Hz2ZRv0AYLsG8rM1biZGdREWx9OaknVVuIo2ivehBiukL7VQ6Bu8ugjep3mn-z666a-nCMh6ZuASiQ6Geq0NSWmdDQIoCa5Hg44KzMfGRlCR2uKBXeHTD0SkwJ1VJM0sHNKwSfMXKpaX8OJ5wUJpgCzDzQwKVgxgWFp4eO_sbcvxWrpI7W0lfdCy1WKirnZ6Uh3uJ06v97GQDAQqVgBZFEpS47MrGZhTNuAG4ZbfYO7yyxVO8AHQbEC-UvZ-8DC1XZjvQ6S1uNqQIlVGcthnrxg8K6vKVhNzu6ifQI0bbsCl8bGsKkXOEK1pKR3ekckcSjNeeY2LrcdXs8F2gtkm0TjXU"
}

Authenticate as Profile

Obtain a new JWT token for a Profile. If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey required	string Profile API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://help.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles.

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": { },
"tags": ["string"
]
}

Response samples

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate as Profile (conditional)

Obtain a new JWT token for a Profile.

If the account does not exist, an account is not created.
If any additional conditions are required for logging in, the response is HTTP200 and lists the conditions.
Note that using this endpoint requires authenticating as an anonymous Profile first.
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey required	string Profile API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://help.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles.

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": { },
"tags": ["string"
]
}

Response samples

Content type

application/json

{"conditions": ["string"
],
"status": "SUCCESS",
"token": "string"
}

Authenticate anonymously

Obtain a new JWT for an anonymous Profile. The token can be used and refreshed in the same way as tokens of registered Profiles.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey	string Profile API key (same as for Profile login)
deviceId	string Unique Android or iOS device ID
uuid	string UUID of the Profile. It is a unique identifier.

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"deviceId": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f"
}

Response samples

200
401

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Log in as User

Authenticate as a User.

Note: To perform operations within a Workspace, you must select a Workspace.

This method does not require a Synerise authorization token.

Request Body schema: application/json

username required	string The login (email address) of the user
password required	string The user's password
deviceId	string Identifier of user's current device
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"username": "string",
"password": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Verify User multi-factor authentication

Authenticate as a User with multi-factor authentication.

Note: To perform operations within a Workspace, you must select a Workspace.

API consumer who can use this method: Synerise User
This method is available to all authenticated users, before and after multi-factor authentication is confirmed.

Authorizations:

JWT

query Parameters

mfaType

required

string

Value: "TOTP_AUTHENTICATOR"

Type of multi-factor authentication

Request Body schema: application/json

verificationCode required	string Multi-factor verification code
deviceId	string
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"verificationCode": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Select Workspace

After logging in as a User, select a Workspace where you want to perform operations.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

path Parameters

businessProfileUUID

required

string <uuid>

UUID of the workspace

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/uauth/auth/login/user/profile/%7BbusinessProfileUUID%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
423

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Get Workspaces

Retrieve a list of Workspaces available to the user.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/ 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"businessProfileGuid": "string",
"logo": "string",
"name": "string",
"id": 0,
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestricted": true,
"mfaRequired": true
}
]

Get current Workspace

Retrieve information about the currently selected workspace.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/current 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"businessProfileGuid": "string",
"logo": "string",
"name": "string",
"id": 0,
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestricted": true,
"mfaRequired": true
}

Log in as Workspace

Obtain a new Workspace JWT Token.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey

required

string

Workspace API key

Responses

Request samples

Content type

application/json

{"apiKey": "64c09614-1b2a-42f7-804d-f647243eb1ab"
}

Response samples

200
400
401

Content type

application/json

{"token": "string"
}

Search

AI-powered search engine management and usage

Full-text items search

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 who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

query required	string Query text to use in the search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string Correlation 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.
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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
distinctFilter	string Example: distinctFilter={"attribute": "color", "maxNumItems": 3} DistinctFilter JSON as an URL-encoded string

Responses

Request samples

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%2C15.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=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=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' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Full-text items search

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 who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json

Request for performing full-text search

query required	string Query text to use in the search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `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
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string `correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A 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.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
	object Distinct filters regulate how many items with the same value of a particular attribute can be returned.

Responses

Request samples

Content type

application/json

{"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",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
}
}

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Autocomplete items search

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 who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

query required	string Query text to use in the search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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
distinctFilter	string Example: distinctFilter={"attribute": "color", "maxNumItems": 3} DistinctFilter JSON as an URL-encoded string

Responses

Request samples

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%2C15.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=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=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' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Autocomplete items search

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 who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json

Request for performing an autocomplete search

query required	string Query text to use in the search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `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
clientUUID	string UUID of the profile for which the search is performed
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A 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.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
	object Distinct filters regulate how many items with the same value of a particular attribute can be returned.

Responses

Request samples

Content type

application/json

{"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",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
}
}

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Get deleted searches

Retrieve the searches deleted from a profile's history.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID

required

string

Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1

UUID of the profile for which the query is performed

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/deleted-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
400

Content type

application/json

[{"query": "string",
"match": "query",
"timestamp": "2019-08-24T14:15:22Z"
}
]

Soft-delete a recent search

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 who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_CREATE

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID

required

string

Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1

UUID of the profile for which the query is performed

Request Body schema: application/json

Request for deleting search query

query	string Deleted search query. Required if `match` field is set to `query`.
match	string Default: "query" Tells how to match this deleted search on recent searches. `query`: matches only recent searches with provided query `all`: matches all recent searches
timestamp	string <date-time> Time when the search was deleted. If not present current time is taken.

Responses

Request samples

Content type

application/json

{"query": "string",
"match": "query",
"timestamp": "2019-08-24T14:15:22Z"
}

Response samples

400

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get recent searches

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

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID required	string Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1 UUID of the profile for which the query is performed
windowSize	integer >= 1 Default: 15 Maximum 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.
timeUnit	string Default: "DAYS" Enum: "YEARS" "MONTHS" "WEEKS" "DAYS" "HOURS" "MINUTES" "SECONDS" The 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.
timeValue	integer >= 1 Default: 30 The 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

Request samples

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

Response samples

200
400

Content type

application/json

["string"
]

Visual Search

Visual Search methods

Visual items search

Retrieves items that match an image. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

url required	string URL of the image to be used in the visual search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string Correlation 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.
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filterAnchor	string Example: filterAnchor=0.2,0.8 Anchor (`{width},{height}`) by which the visual results data will be filtered. `{width},{height}` correspond to normalized image coordinates, i.e. they are in range [0,1]. Anchor (0,0) corresponds to the top-left pixel of an image.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/visual?url=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%2C15.0%2C65.0&filterAroundRadius=5000&filterAnchor=0.2%2C0.8&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Visual items search

Retrieves items that match an image. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema:
application/json
application/json
multipart/form-data

Request for performing visual search

url required	string URL of the image to be used in the visual search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `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
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string `correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filterAnchor	string Anchor (`{width},{height}`) by which the visual results data will be filtered. `{width},{height}` correspond to normalized image coordinates, i.e. they are in range [0,1]. Anchor (0,0) corresponds to the top-left pixel of an image.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A 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.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item

Responses

Request samples

Content type

{"url": "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,
"filterAnchor": "0.2,0.8",
"filters": "string",
"facets": ["string"
],
"customFilteredFacets": {"brand": "price > 100",
"price": "brand == foo"
},
"facetsSize": 2000,
"maxValuesPerFacet": 50,
"caseSensitiveFacetValues": false,
"includeFacets": "all",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
]
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Listing

Retrieve items from an item catalog

Items listing

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

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string Correlation 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.
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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
distinctFilter	string Example: distinctFilter={"attribute": "color", "maxNumItems": 3} DistinctFilter JSON as an URL-encoded string

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/list?clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685%2C15.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=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=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' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Items listing

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

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json

Request for item listing

page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 500 Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `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
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string `correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
searchId	string Deprecated DEPRECATED - 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.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The 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. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. 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"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A 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.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines 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.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
	object Distinct filters regulate how many items with the same value of a particular attribute can be returned.

Responses

Request samples

Content type

application/json

{"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",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
}
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Synonyms

Synonym configuration and usage

Get synonyms

Retrieve a list of synonyms.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string <uuid>

Index identifier

query Parameters

page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 1000 Default: 1000 Example: limit=100 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/synonyms?page=4&limit=100&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"data": [{"id": 0,
"type": "oneway",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "string"
}
],
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Create synonym

Creates a new synonym.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema: application/json

Request for creating new synonym

type	string Default: "oneway" Enum: "oneway" "synonyms" Type of the synonym. `oneway`: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. `synonyms`: the `word` column is empty, all phrases in `synonym` return results for every other phrase in the list.
word	string The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms required	Array of strings A list of synonyms

Responses

Request samples

Content type

application/json

{"type": "oneway",
"word": "string",
"synonyms": ["string"
]
}

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "oneway",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "string"
}

Duplicate synonyms

Duplicate synonyms from source index to duplicate index at once.

API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: INTERNAL

Authorizations:

JWT

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema: application/json

Request for duplicating synonyms from one index to another

duplicateIndexId

required

string

ID of the target index

Responses

Request samples

Content type

application/json

{"duplicateIndexId": "string"
}

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Batch insert synonyms

Insert multiple synonyms into an index at once.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema:
text/csv
text/csv
multipart/form-data

The CSV has three columns:

word: the phrase to replace with a synonym
synonyms: the synonyms of the word (if more than one, the list is comma-separated and enclosed with "")
type: the relation type:
- oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms.
- synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.

word	string The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms	Array of strings A list of synonyms
type	string Default: "oneway" Enum: "oneway" "synonyms" Type of the synonym. `oneway`: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. `synonyms`: the `word` column is empty, all phrases in `synonym` return results for every other phrase in the list.

Responses

Request samples

Content type

word,synonyms,type
dog,"doggy,puppy",oneway
small horse,pony,oneway
,"cat,kitten,kitty,tabby cat",synonyms

Response samples

200
500

Content type

application/json

{"attemptedInserts": 0,
"actualInserts": 0,
"errors": ["string"
]
}

Replace all synonyms

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema:
text/csv
text/csv
multipart/form-data

The CSV has three columns:

word: the phrase to replace with a synonym
synonyms: the synonyms of the word (if more than one, the list is comma-separated and enclosed with "")
type: the relation type:
- oneway: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms.
- synonyms: the word column is empty, all phrases in synonym return results for every other phrase in the list.

word	string The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms	Array of strings A list of synonyms
type	string Default: "oneway" Enum: "oneway" "synonyms" Type of the synonym. `oneway`: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. `synonyms`: the `word` column is empty, all phrases in `synonym` return results for every other phrase in the list.

Responses

Request samples

Content type

word,synonyms,type
dog,"doggy,puppy",oneway
small horse,pony,oneway
,"cat,kitten,kitty,tabby cat",synonyms

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get synonym

Retrieves a synonym.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

synonymId required	integer Synonym identifier
indexId required	string <uuid> Index identifier

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "oneway",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "string"
}

Update synonym

Updates a synonym identified by id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

synonymId required	integer Synonym identifier
indexId required	string <uuid> Index identifier

Request Body schema: application/json

Request for creating new synonym

type	string Default: "oneway" Enum: "oneway" "synonyms" Type of the synonym. `oneway`: when the word is searched, the results show the results as if the synonyms were searched. Searching for the synonyms does NOT return results for the word or the other synonyms. `synonyms`: the `word` column is empty, all phrases in `synonym` return results for every other phrase in the list.
word	string The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms required	Array of strings A list of synonyms

Responses

Request samples

Content type

application/json

{"type": "oneway",
"word": "string",
"synonyms": ["string"
]
}

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "oneway",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "string"
}

Delete synonym

Deletes a synonym with given id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SYNONYMS_SEARCH_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

synonymId required	integer Synonym identifier
indexId required	string <uuid> Index identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Configuration

AI search engine settings

Get configurations of all indices

Retrieve the configurations of all indices.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 1000 Default: 1000 Example: limit=100 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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
name	string Only indices containing this name will be retrieved.
excludeAbTests	boolean Only indices not involved in currently running AB tests will be retrieved.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"data": [{"indexId": "string",
"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Post index configuration

Creates a new configuration of a single index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

Request Body schema: application/json

Request for posting search configuration

indexName required	string Human-friendly name of the index
description	string Description of the index
itemsCatalogId required	string ID of the item catalog from which the index will be created
language required	string Search language as ISO 639-1 code
enabled required	boolean When `true`, the index is enabled and can be queried.
ignoreUnavailableItems	boolean Default: true When `true`, unavailable items are not indexed, which makes the search run faster.
	object Item scoring settings that affect the presentation order of the results. `0` means the lowest importance of a parameter, `1` is the highest importance.
	object Controls manner in which suggestions are generated
	object or object or object Used for tokenizing full text into individual words
attributesWithoutPrefixSearch	Array of strings Searchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerance	Array of strings Searchable attributes for which typo tolerance is off
valuesWithoutTypoTolerance	Array of strings Attributes values for which typo tolerance is off
typoToleranceOnNumericValues	boolean Default: true When `true`, typo tolerance is active on numbers
required	object The attributes that are taken into account as full text search terms
displayableAttributes	Array of strings Attributes shown in the search results
	object Attributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
	object Attributes for which filters can be used
	object Attributes using which search results can be sorted
	object Attributes for which distinct can be used
	object Recent searches configuration

Responses

Request samples

Content type

application/json

{"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
}
}

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Get index configuration

Retrieve the configuration of a single index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Update index configuration

Update the configuration of a single index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json

Request for posting search configuration

indexName required	string Human-friendly name of the index
description	string Description of the index
itemsCatalogId required	string ID of the item catalog from which the index will be created
language required	string Search language as ISO 639-1 code
enabled required	boolean When `true`, the index is enabled and can be queried.
ignoreUnavailableItems	boolean Default: true When `true`, unavailable items are not indexed, which makes the search run faster.
	object Item scoring settings that affect the presentation order of the results. `0` means the lowest importance of a parameter, `1` is the highest importance.
	object Controls manner in which suggestions are generated
	object or object or object Used for tokenizing full text into individual words
attributesWithoutPrefixSearch	Array of strings Searchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerance	Array of strings Searchable attributes for which typo tolerance is off
valuesWithoutTypoTolerance	Array of strings Attributes values for which typo tolerance is off
typoToleranceOnNumericValues	boolean Default: true When `true`, typo tolerance is active on numbers
required	object The attributes that are taken into account as full text search terms
displayableAttributes	Array of strings Attributes shown in the search results
	object Attributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
	object Attributes for which filters can be used
	object Attributes using which search results can be sorted
	object Attributes for which distinct can be used
	object Recent searches configuration

Responses

Request samples

Content type

application/json

{"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
}
}

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Delete index configuration

Delete the configuration of a single index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get index state

Retrieve the state of a single index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"indexId": "string",
"state": "NotReady",
"lastConfigChange": "2019-08-24T14:15:22Z",
"errorReason": "string",
"log": "string"
}

Get supported languages

Retrieve supported languages.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"pl": "Polish",
"ro": "Romanian",
"ru": "Russian"
}

Duplicate index

duplicate index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"itemsCatalogId": "string",
"language": "string",
"enabled": true,
"ignoreUnavailableItems": true,
"scoring": {"pageVisitsPopularity": 0,
"transactionsPopularity": 0,
"personalized": 0,
"tieBreaker": 0,
"matching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Get values of filterable attributes

Retrieve values of filterable attributes.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

attribute

required

Array of strings

List of attributes for which values will be fetched

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"brand": ["foo",
"bar"
],
"color": ["red",
"green",
"blue"
]
}

Suggestions Configuration

Settings for AI search suggestions

Get suggestion indices

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 1000 Default: 1000 Example: limit=100 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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
name	string Only indices containing this name will be retrieved.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"data": [{"indexId": "string",
"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
],
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Create suggestion index

Create a suggestion index configuration.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

Request Body schema: application/json

indexName required	string Name of the suggestion index
description	string Description of the suggestion index
author	integer ID of the user who created the suggestion index
enabled required	boolean When `true`, index is enabled and can be queried.
required	object Sources for the suggestions
	Array of objects[ items ] Suggestions that will be ignored and not shown

Responses

Request samples

Content type

application/json

{"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
]
}

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
],
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Get suggestion index

Retrieve a suggestion index configuration.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
],
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Create/replace suggestion index

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json

indexName required	string Name of the suggestion index
description	string Description of the suggestion index
author	integer ID of the user who created the suggestion index
enabled required	boolean When `true`, index is enabled and can be queried.
required	object Sources for the suggestions
	Array of objects[ items ] Suggestions that will be ignored and not shown

Responses

Request samples

Content type

application/json

{"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
]
}

Response samples

200
500

Content type

application/json

{"indexId": "string",
"indexName": "string",
"description": "string",
"author": 0,
"enabled": true,
"sources": {"indices": [{"indexId": "string",
"minPopularity": 5,
"minHits": 1,
"minLetters": 2,
"daysInterval": 30,
"validate": false
}
],
"external": [{"query": "string",
"count": 0
}
],
"generate": [{"itemsCatalogId": "string",
"attributes": ["string"
]
}
]
},
"denylist": [{"pattern": "string",
"matchingType": "Phrase"
}
],
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}

Delete suggestion index

Delete a suggestion index configuration.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get suggestion index state

Retrieve the state of a single suggestion index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_CONFIG_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"indexId": "string",
"state": "NotReady",
"lastConfigChange": "2019-08-24T14:15:22Z",
"errorReason": "string",
"log": "string"
}

Query Rules

Query rule configuration for the AI search engine

Get rules

Retrieves a list of rules.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

query Parameters

status	string Enum: "finished" "draft" "paused" "scheduled" "active" Only rules with this status will be retrieved.
name	string Only rules containing this name will be retrieved.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> <= 1000 Default: 1000 Example: limit=100 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `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

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"data": [{"status": "string",
"rule": {"id": 0,
"name": "string",
"author": 0,
"state": "draft",
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"updatedAt": "string",
"createdAt": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}
}
],
"extras": {"statuses": {"Finished": 0,
"Draft": 0,
"Paused": 0,
"Scheduled": 0,
"Active": 0
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Create rule

Creates a new rule.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json

Request for posting a new rule or updating an existing one

name	string Name of the rule
author	integer The user who created the rule
activeFrom	string Time when the rules becomes active, in YYYY-MM-DD HH-MM-SS format
activeTo	string Time when the rule becomes inactive, in YYYY-MM-DD HH-MM-SS format
timezone	string Timezone in `UTC[+/-]X` format, for example `UTC+4`, `UTC+0`, `UTC-3`
	object This object contains the details of what the rule does

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"author": 0,
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}

Response samples

200
500

Content type

application/json

{"status": "string",
"rule": {"id": 0,
"name": "string",
"author": 0,
"state": "draft",
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"updatedAt": "string",
"createdAt": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}
}

Duplicate rules

Duplicate list of rules

API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: INTERNAL

Authorizations:

JWT

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json

Request for duplicating rules from one index to another

duplicateIndexId

required

string

ID of the index

Responses

Request samples

Content type

application/json

{"duplicateIndexId": "string"
}

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get rule

Retrieves a rule.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"status": "string",
"rule": {"id": 0,
"name": "string",
"author": 0,
"state": "draft",
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"updatedAt": "string",
"createdAt": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}
}

Update query rule

Updates a rule identified by id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Request Body schema: application/json

Request for posting a new rule or updating an existing one

name	string Name of the rule
author	integer The user who created the rule
activeFrom	string Time when the rules becomes active, in YYYY-MM-DD HH-MM-SS format
activeTo	string Time when the rule becomes inactive, in YYYY-MM-DD HH-MM-SS format
timezone	string Timezone in `UTC[+/-]X` format, for example `UTC+4`, `UTC+0`, `UTC-3`
	object This object contains the details of what the rule does

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"author": 0,
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}

Response samples

200
500

Content type

application/json

{"status": "string",
"rule": {"id": 0,
"name": "string",
"author": 0,
"state": "draft",
"activeFrom": "string",
"activeTo": "string",
"timezone": "string",
"updatedAt": "string",
"createdAt": "string",
"data": {"audience": {"segmentationIds": ["34ab56cd-789be-22ee-11ab-123456789abc",
"12xy34z5-456b-33cc-7o52-987654321ece"
]
},
"conditions": {"patterns": ["phone",
"notebook",
"mouse {color} {brand}"
],
"matchingType": "is",
"contexts": ["listing",
"web",
"mobile"
],
"filters": {"textFilters": {"color": {"values": ["green",
"red"
],
"matchingType": "InUserFilters"
}
},
"rangeFilters": {"price": {"ranges": [{"rightEnd": {"value": 20,
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"standardFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"elasticFilters": {"textFilters": [{"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"value": "{price}"
}
]
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}
}

Delete rule

Deletes a rule identified by id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Activate rule

Activates a rule identified by id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Pause rule

Pauses a rule identified by id.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Draft rule

Marks a rule as draft.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Finish rule

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: QUERY_RULES_SEARCH_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId required	string ID of the index
ruleId required	integer Rule identifier

Responses

Request samples

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

Response samples

500

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Analytics

Statistics for the AI-powered search engine

Get queries stats summary

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/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 _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0
}

Get top queries

Retrieves the 1000 most popular queries.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
queryFilter	string Default: "queries" Enum: "queries" "queriesWithNoResults" "queriesWithUsedSuggestions" Queries for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/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' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"count": 0
}
]

Get filters stats

Retrieves the statistics of filters used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

filterName	string Example: filterName=brand Name of the filterable attribute. If present top values of this filter are returned.
dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/filters/summary?filterName=brand&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"filterName": "string",
"count": 0
}
]

Get rules stats

Retrieves the statistics of applied rules.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"ruleId": 0,
"count": 0
}
]

Get queries summary for multiple indices

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

indexId required	Array of strings List of indices ids for which the stats are requested.
dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

[{"indexId": "4add1a1fa877c1651906bb22c9dfd37a1618852272",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0
}
}
]

Query stats summary

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}

Query stats grouped by date

Retrieves query statistics grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries

Retrieve the statistics of the 1000 most popular queries.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries grouped by date

Retrieve the statistics of the 1000 most popular queries, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]
}
]

Stats of queries with suggestions used

Retrieves the statistics of queries where the customer accepted a suggestion.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}

Stats of queries with suggestions used grouped by date

Retrieves the statistics of queries where a customer accepted a suggestion, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries with used suggestions

Retrieves the statistics of the 1000 most popular queries where the customer accepted a suggestion.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries with used suggestions grouped by date

Retrieves the statistics of the 1000 most popular queries where the customer accepted a suggestion, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]
}
]

Stats of queries with no results

Retrieves the statistics of searches which returned no results.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"totalCount": 0
}

Stats of queries with no results grouped by date

Retrieves the statistics of searches which returned no results, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"totalCount": 0
}
}
]

Get stats of top queries with no results

Retrieves the statistics of the 1000 most popular queries which returned no results.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"totalCount": 0
}
}
]

Stats of top queries with no results grouped by date

Retrieves the statistics of the 1000 most popular queries which returned no results, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"totalCount": 0
}
}
]
}
]

Stats of filters

Retrieves the statistics of filters used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"filterName": "string"
}
]

Stats of filters grouped by date

Retrieves the statistics of filters used in searches, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"filterName": "string"
}
]
}
]

Stats of a single filter

Retrieves the statistics of a single filter used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

filterName

required

string

Name of the filter

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/%7BfilterName%7D/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"filterValue": "string"
}
]

Stats of a single filter grouped by date

Retrieves the statistics of a single filter used in searches, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

filterName

required

string

Name of the filter

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/%7BfilterName%7D/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"filterValue": "string"
}
]
}
]

Stats of applied query rules

Retrieve the statistics of applied query rules.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"ruleId": "string"
}
]

Stats of applied query rules grouped by date

Retrieve the statistics of applied query rules, grouped by date.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/rules/group/date/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"ruleId": "string"
}
]
}
]