AI Search (Jan 13, 2026, 11:17:08 AM)

Download OpenAPI specification:

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 [email protected].

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 authentication.

Authorizations:

JWT

Request Body schema: application/json
required

apiKey

required

string (ClientApiKey)

Profile (formerly "Client") API key

Responses

Request samples

Content type

application/json

{"apiKey": "string"
}

Response samples

200
401

Content type

application/json

{"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

Authenticate as Profile

Obtain a new JWT 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 authentication.

Request Body schema: application/json

apiKey required	string (ClientApiKey) Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string (AuthIdentityProviderToken) Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string (AuthClientEmail) Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any (AuthClientCustomId) Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string (AuthClientPassword) Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string (AuthClientUuid) Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string (inBodyClientDeviceId) Unique Android or iOS device ID
	object (Agreements) Marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"TRUE"`;`"True"`/`"false"`;`"FALSE"`;`"False"`) or integers (`1` for true and `0` for false).
	object (Attributes) Custom attributes (with any names) WARNING: Some attributes cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the `attributes` object. Click to expand the list of reserved attributes `email` `id` `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` `zipCode` `anonymous_type` `country_id` `geo_loc_country` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `club_card_id` `type` `confirmed` `facebookId` `deletedAt` `deleted_unique` `status` `recognized` `previous_clients` `testProfile` `apikey` `apiKey` `ApiKey` `Apikey` `tracker` `snr_sdk_version` `eventCreateTime` `correlationId`
tags	Array of strings (Tags) An array of tags assigned to the campaign

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": true,
"sms": true,
"push": true,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"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 Profile with a server

Obtain a new JWT for a Profile. This method is designed to be used from a backend server that handles login requests and communicates with Synerise to execute them.
If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

API consumer who can use this method: Workspace (formerly Business Profile)
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: SAUTH_SERVER_LOGIN_CLIENT_CREATE

Request Body schema: application/json

ipAddress required	string The IP address of the client device that is logging in.
apiKey required	string (ClientApiKey) Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string (AuthIdentityProviderToken) Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string (AuthClientEmail) Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any (AuthClientCustomId) Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string (AuthClientPassword) Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string (AuthClientUuid) Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string (inBodyClientDeviceId) Unique Android or iOS device ID
	object (Agreements) Marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"TRUE"`;`"True"`/`"false"`;`"FALSE"`;`"False"`) or integers (`1` for true and `0` for false).
	object (Attributes) Custom attributes (with any names) WARNING: Some attributes cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the `attributes` object. Click to expand the list of reserved attributes `email` `id` `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` `zipCode` `anonymous_type` `country_id` `geo_loc_country` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `club_card_id` `type` `confirmed` `facebookId` `deletedAt` `deleted_unique` `status` `recognized` `previous_clients` `testProfile` `apikey` `apiKey` `ApiKey` `Apikey` `tracker` `snr_sdk_version` `eventCreateTime` `correlationId`
tags	Array of strings (Tags) An array of tags assigned to the campaign

Responses

Request samples

Content type

application/json

{"ipAddress": "string",
"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": true,
"sms": true,
"push": true,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"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 authentication.

Authorizations:

JWT

Request Body schema: application/json

apiKey required	string (ClientApiKey) Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string (AuthIdentityProviderToken) Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string (AuthClientEmail) Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any (AuthClientCustomId) Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string (AuthClientPassword) Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string (AuthClientUuid) Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string (inBodyClientDeviceId) Unique Android or iOS device ID
	object (Agreements) Marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"TRUE"`;`"True"`/`"false"`;`"FALSE"`;`"False"`) or integers (`1` for true and `0` for false).
	object (Attributes) Custom attributes (with any names) WARNING: Some attributes cannot be sent in this object and will be ignored. Some of these are reserved for system use, and others must be sent as properties of the profile in the root object of the request body instead of inside the `attributes` object. Click to expand the list of reserved attributes `email` `id` `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` `zipCode` `anonymous_type` `country_id` `geo_loc_country` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `club_card_id` `type` `confirmed` `facebookId` `deletedAt` `deleted_unique` `status` `recognized` `previous_clients` `testProfile` `apikey` `apiKey` `ApiKey` `Apikey` `tracker` `snr_sdk_version` `eventCreateTime` `correlationId`
tags	Array of strings (Tags) An array of tags assigned to the campaign

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": true,
"sms": true,
"push": true,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"conditions": ["string"
],
"status": "SUCCESS",
"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

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 authentication.

Request Body schema: application/json
required

apiKey required	string (ClientApiKey) Profile (formerly "Client") API key
uuid required	string (inBodyClientUuid) UUID of the Profile
deviceId	string Unique iOS or Android device identifier.

Responses

Request samples

Content type

application/json

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

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 authentication.

Request Body schema: application/json
required

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 (MultiFactorMethod)

Enum: "TOTP_AUTHENTICATOR" "EMAIL"

Type of multi-factor authentication

Request Body schema: application/json
required

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 REPLACE_BEARER_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 REPLACE_BEARER_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 Workspaces ids with user-specific data

Retrieve a list of workspace ids available to the user, with added user-specific data

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/ids \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

200

Content type

application/json

[{"id": 0,
"ipRestriction": "OFF",
"mfaRestriction": "OFF",
"favorite": 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 REPLACE_BEARER_TOKEN'

Response samples

200

Content type

application/json

{"selected": true,
"data": {"id": 0,
"name": "string",
"logo": "string",
"businessProfileGuid": "string",
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestriction": "OFF",
"mfaRestriction": "OFF",
"labels": ["string"
],
"emailAttributeName": "string"
}
}

Log in as Workspace

Obtain a new Workspace JWT Token.

This method does not require authentication.

Request Body schema: application/json
required

apiKey

required

string

Workspace API key

WARNING: Workspace API keys can be used to access all customer data and manage the workspace. They should only be used for server-to-server communication in integrations. DO NOT use workspace API keys in your mobile applications or websites.

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

Get deleted searches

Retrieve the searches deleted from a profile's history.

API consumers who can use this method: AI API key (legacy), Workspace (formerly Business Profile), 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:

JWTTrackerKeyBasic

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/4add1a1fa877c1651906bb22c9dfd37a1618852272/deleted-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

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), Workspace (formerly Business Profile), 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:

JWTTrackerKeyBasic

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
required

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

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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), Workspace (formerly Business Profile), 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:

JWTTrackerKeyBasic

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/4add1a1fa877c1651906bb22c9dfd37a1618852272/recent-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1&windowSize=SOME_INTEGER_VALUE&timeUnit=SOME_STRING_VALUE&timeValue=SOME_INTEGER_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
400

Content type

application/json

["string"
]

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
disableQueryClassification	boolean Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean Default: false If set to `true`, dynamic reranker is not applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

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&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE&params=source%3Amobile' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for performing full-text search

query required	string (SearchQuery) Query text to use in the search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.
disableQueryClassification	boolean (DisableQueryClassification) Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean (DisableDynamicReranker) Default: false If set to `true`, q dynamic reranker is not applied.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
},
"disableQueryClassification": false,
"disableDynamicReranker": false
}

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained 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. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
disableQueryClassification	boolean Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean Default: false If set to `true`, dynamic reranker is not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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
},
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true,
"reranker": {"queryClassificationApplied": true,
"dynamicRerankerApplied": true,
"queryClassificationResult": [{"category": "string",
"score": 0,
"ctr": 0.1,
"actions": ["staticFilter"
],
"reliabilityLevel": "certain"
}
]
}
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained 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. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for performing full-text search

query required	string (SearchQuery) Query text to use in the search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.
disableQueryClassification	boolean (DisableQueryClassification) Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean (DisableDynamicReranker) Default: false If set to `true`, q dynamic reranker is not applied.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
},
"disableQueryClassification": false,
"disableDynamicReranker": false
}

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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
},
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true,
"reranker": {"queryClassificationApplied": true,
"dynamicRerankerApplied": true,
"queryClassificationResult": [{"category": "string",
"score": 0,
"ctr": 0.1,
"actions": ["staticFilter"
],
"reliabilityLevel": "certain"
}
]
}
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.
disableQueryClassification	boolean Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean Default: false If set to `true`, dynamic reranker is not applied.

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&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile&disableQueryClassification=SOME_BOOLEAN_VALUE&disableDynamicReranker=SOME_BOOLEAN_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for performing an autocomplete search

query required	string (SearchQuery) Query text to use in the search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
sortByMetric	string (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.
disableQueryClassification	boolean (DisableQueryClassification) Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean (DisableDynamicReranker) Default: false If set to `true`, q dynamic reranker is not applied.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
},
"disableQueryClassification": false,
"disableDynamicReranker": false
}

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained 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. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.
disableQueryClassification	boolean Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean Default: false If set to `true`, dynamic reranker is not applied.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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
},
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true,
"reranker": {"queryClassificationApplied": true,
"dynamicRerankerApplied": true,
"queryClassificationResult": [{"category": "string",
"score": 0,
"ctr": 0.1,
"actions": ["staticFilter"
],
"reliabilityLevel": "certain"
}
]
}
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained 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. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for performing an autocomplete search

query required	string (SearchQuery) Query text to use in the search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
sortByMetric	string (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.
disableQueryClassification	boolean (DisableQueryClassification) Default: false If set to `true`, query classification is not applied.
disableDynamicReranker	boolean (DisableDynamicReranker) Default: false If set to `true`, q dynamic reranker is not applied.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
},
"disableQueryClassification": false,
"disableDynamicReranker": false
}

Response samples

200
500

Content type

application/json

Example

Item search

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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
},
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true,
"reranker": {"queryClassificationApplied": true,
"dynamicRerankerApplied": true,
"queryClassificationResult": [{"category": "string",
"score": 0,
"ctr": 0.1,
"actions": ["staticFilter"
],
"reliabilityLevel": "certain"
}
]
}
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Searchable attributes match

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

API consumers 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:

TrackerKeyJWTBasic

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
itemId required	string Item ID

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"query": {"value": "string",
"tokens": [{"token": "string",
"positions": [{"start": 0,
"end": 0
}
]
}
]
},
"attributes": [{"attribute": "string",
"value": "string",
"tokens": [{"queryToken": "string",
"type": "word",
"start": 0,
"end": 0
}
]
}
]
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

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&filterGeoPoints=15.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=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema:
application/json
required

Request for performing visual search

url required	string (ImageUrl) URL of the image to be used in the visual search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (FilterAnchor) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.

Responses

Request samples

Content type

application/json

{"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"
],
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
}
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained visual items search

Retrieves items that match an image. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

Request samples

curl --request GET \
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/visual/explain?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&filterGeoPoints=15.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=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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",
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained visual items search

Retrieves items that match an image. The results can be filtered and sorted. The response contains an explanation of the factors that influenced the result.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema:
application/json
required

Request for performing visual search

url required	string (ImageUrl) URL of the image to be used in the visual search
page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (FilterAnchor) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.

Responses

Request samples

Content type

application/json

{"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"
],
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
}
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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",
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

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&filterGeoPoints=15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=title&displayAttributes=price&context=mobile&context=listing&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=2&excludeQueryRules=5&params=source%3Amobile' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for item listing

page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
}
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained items listing

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

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

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" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
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. 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> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string Default: "asc" 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
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.
params	Array of strings Example: params=source:mobile List of extra params that will be added to the `item.search` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.

Responses

Request samples

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

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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",
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

Explained items listing

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

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
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:

TrackerKeyJWTBasic

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json
required

Request for item listing

page	integer <int32> (PaginationPage) Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> (PaginationLimit) [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string (PaginationSortBy) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the attribute by which the data will be sorted.
ordering	string (PaginationOrdering) Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean (PaginationIncludeMeta) 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 (ClientUUID) UUID of the profile for which the search is performed
personalize	boolean (Personalize) Default: true If set to `false`, the search result is not personalized.
correlationId	string (CorrelationId) 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 (SearchId) 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 (SortByMetric) Enum: "TransactionsPopularity" "PageVisitsPopularity" IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Name of the metric by which the data will be sorted.
sortByGeoPoints	string (SortByGeoPoint) IMPORTANT: Sorting disables boosting, elastic filters, and promoting search results. Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".'
filterGeoPoints	Array of strings (FilterGeoPoints) 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. 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> (FilterAroundRadius) 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 (Filters) IQL query string. For details, see the Help Center.
facets	Array of strings (Facets) 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 (CustomFilteredFacets) 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 (FacetsSize) [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer (MaxValuesPerFacet) [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean (CaseSensitiveFacetValues) Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string (IncludeFacets) 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` and `customFilteredFacets` parameters.
context	Array of strings (Context) List of context strings for a search query
displayAttributes	Array of strings (DisplayAttributes) List of ad hoc attributes that will be returned for each found item
	object (DistinctFilterSearch) Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean (IgnoreQueryRules) Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers (ExcludeQueryRules) List of query rules that will not be applied.
	object (Params) Extra parameters that will be added to the `item.search` event. The total size must not exceed 500 bytes.

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
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
],
"params": {"source": "mobile"
}
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"allFacets": {"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",
"explanation": {"rulesConsequences": {"query": {"originalQuery": "string",
"finalQuery": "string",
"modifications": [{"slice": {"from": 0,
"to": 0
},
"transformedSlice": {"from": 0,
"to": 0
},
"ruleId": 0
}
]
},
"hiddenHits": [{"id": "string",
"ruleIds": [0
]
}
],
"filters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"ruleId": 0
}
],
"boostFilters": [{"filters": {"textFilters": [{"attribute": "string",
"mode": "include",
"values": ["A-Brand",
"B-Brand"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": 19.99
}
]
},
"weight": 0,
"ruleId": 0
}
],
"returnNoData": {"enabled": true,
"ruleIds": [0
]
}
},
"sortDetails": {"metric": "TransactionsPopularity",
"ordering": "asc"
},
"query": {"finalQuery": "string",
"synonyms": [{"word": "string",
"synonyms": ["string"
]
}
]
},
"personalized": true,
"promotedItemsCount": 0,
"wasFallbackMatchingUsed": true
}
},
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

{"data": [{"id": 0,
"type": "string",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "string"
}
],
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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:

JWTBasic

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema: application/json
required

Request for creating new synonym

type	string (Type) Generic counter type
word	string (Word) The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms required	Array of strings (Synonyms) A list of synonyms

Responses

Request samples

Content type

application/json

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

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "string",
"word": "string",
"synonyms": ["string"
],
"createdAt": "string",
"updatedAt": "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:

JWTBasic

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema:
text/csv
required

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 (Word) The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms	Array of strings (Synonyms) A list of synonyms
type	string (Type) Generic counter type

Responses

Request samples

Content type

text/csv

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:

JWTBasic

path Parameters

indexId

required

string <uuid>

Index identifier

Request Body schema:
text/csv
required

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 (Word) The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms	Array of strings (Synonyms) A list of synonyms
type	string (Type) Generic counter type

Responses

Request samples

Content type

text/csv

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

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "string",
"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:

JWTBasic

path Parameters

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

Request Body schema: application/json
required

Request for creating new synonym

type	string (Type) Generic counter type
word	string (Word) The phrase that the synonym relates to. If `type: synonyms`, do not send this value.
synonyms required	Array of strings (Synonyms) A list of synonyms

Responses

Request samples

Content type

application/json

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

Response samples

200
500

Content type

application/json

{"id": 0,
"type": "string",
"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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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 Deprecated Deprecated parameter. If `query` is provided, this parameter is ignored. If an index has an `id` equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their `name` will be retrieved.
query	string If an index has an `id` equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their `name` will be retrieved. This parameter replaces the deprecated `name` parameter.
excludeAbTests	boolean Only indices not involved in currently running AB tests will be retrieved.
directoryId	string <uuid> Requested directoryId of the rule.
type	string Enum: "Keyword" "Hybrid" "Semantic" Requested type of the rule.

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&query=SOME_STRING_VALUE&excludeAbTests=SOME_BOOLEAN_VALUE&directoryId=SOME_STRING_VALUE&type=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
},
"updatedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
],
"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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:

JWTBasic

Request Body schema: application/json
required

Request for posting search configuration

indexName required	string (IndexNameSchema) Human-friendly name of the index
description	string (IndexDescriptionSchema) Description of the index
itemsCatalogId required	string (ItemsCatalogIdSchema) ID of the item catalog from which the index will be created
language required	string (LanguageSchema) Search language as ISO 639-1 code
enabled required	boolean (EnabledSchema) When `true`, the index is enabled and can be queried.
ignoreUnavailableItems	boolean (IgnoreUnavailableItemsSchema) Default: true When `true`, unavailable items are not indexed, which makes the search run faster.
	object (ScoringSchema) 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 (Suggestions) Controls manner in which suggestions are generated
	WhitespaceTokenizer (object) or StandardTokenizer (object) or PatternTokenizer (object) (Tokenizer) Used for tokenizing full text into individual words
	object (Analyzers) Controls analyzer settings.
attributesWithoutPrefixSearch	Array of strings (AttributesWithoutPrefixSearchSchema) Searchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerance	Array of strings (AttributesWithoutTypoToleranceSchema) Searchable attributes for which typo tolerance is off
valuesWithoutTypoTolerance	Array of strings (ValuesWithoutTypoToleranceSchema) Attributes values for which typo tolerance is off
typoToleranceOnNumericValues	boolean (TypoToleranceOnNumericValuesSchema) Default: true When `true`, typo tolerance is active on numbers
required	object (SearchableAttributesSchema) The attributes that are taken into account as full text search terms
displayableAttributes	Array of strings (DisplayableAttributesSchema) Attributes shown in the search results
	object (FacetableAttributesSchema) Attributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
	object (FilterableAttributesSchema) Attributes for which filters can be used
	object (SortableAttributesSchema) Attributes using which search results can be sorted
	object (DistinctFilterAttributesSchema) Attributes for which distinct can be used
	object (RecentSearchesConfig) Recent searches configuration
	object (RerankingSchema) Reranking configuration
	object (GeoSearchSchema) Geo search configuration
	object (QueryRulesSchema) Configuration for custom behavior of query rules at the index level.

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
}
}

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
},
"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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
},
"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:

JWTBasic

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json
required

Request for posting search configuration

indexName required	string (IndexNameSchema) Human-friendly name of the index
description	string (IndexDescriptionSchema) Description of the index
itemsCatalogId required	string (ItemsCatalogIdSchema) ID of the item catalog from which the index will be created
language required	string (LanguageSchema) Search language as ISO 639-1 code
enabled required	boolean (EnabledSchema) When `true`, the index is enabled and can be queried.
ignoreUnavailableItems	boolean (IgnoreUnavailableItemsSchema) Default: true When `true`, unavailable items are not indexed, which makes the search run faster.
	object (ScoringSchema) 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 (Suggestions) Controls manner in which suggestions are generated
	WhitespaceTokenizer (object) or StandardTokenizer (object) or PatternTokenizer (object) (Tokenizer) Used for tokenizing full text into individual words
	object (Analyzers) Controls analyzer settings.
attributesWithoutPrefixSearch	Array of strings (AttributesWithoutPrefixSearchSchema) Searchable attributes which will not be used in a prefix search
attributesWithoutTypoTolerance	Array of strings (AttributesWithoutTypoToleranceSchema) Searchable attributes for which typo tolerance is off
valuesWithoutTypoTolerance	Array of strings (ValuesWithoutTypoToleranceSchema) Attributes values for which typo tolerance is off
typoToleranceOnNumericValues	boolean (TypoToleranceOnNumericValuesSchema) Default: true When `true`, typo tolerance is active on numbers
required	object (SearchableAttributesSchema) The attributes that are taken into account as full text search terms
displayableAttributes	Array of strings (DisplayableAttributesSchema) Attributes shown in the search results
	object (FacetableAttributesSchema) Attributes for which facets are returned in the search response. By default, all facetable attributes are also filterable and sortable.
	object (FilterableAttributesSchema) Attributes for which filters can be used
	object (SortableAttributesSchema) Attributes using which search results can be sorted
	object (DistinctFilterAttributesSchema) Attributes for which distinct can be used
	object (RecentSearchesConfig) Recent searches configuration
	object (RerankingSchema) Reranking configuration
	object (GeoSearchSchema) Geo search configuration
	object (QueryRulesSchema) Configuration for custom behavior of query rules at the index level.

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
}
}

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
},
"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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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:

JWTBasic

Responses

Request samples

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

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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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
},
"fallbackMatching": {"type": "MinimumMatching",
"value": 1
},
"similarity": {"type": "BM25",
"k1": 1.2,
"b": 0.75
}
},
"suggestions": {"smoothingModel": "Popularity",
"gramSize": 3,
"maxErrors": 2,
"minWordLength": 4,
"useAlways": false
},
"tokenizer": {"type": "Whitespace"
},
"analyzers": {"autocomplete": "Ngram"
},
"attributesWithoutPrefixSearch": ["brand",
"color",
"promotion.type"
],
"attributesWithoutTypoTolerance": ["itemId",
"link"
],
"valuesWithoutTypoTolerance": ["Nike",
"blue",
"74997"
],
"typoToleranceOnNumericValues": true,
"searchableAttributes": {"fullText": ["brand",
"color",
"promotion.type"
],
"fullTextBoosted": ["brand",
"color",
"promotion.type"
],
"fullTextStronglyBoosted": ["brand",
"color",
"promotion.type"
]
},
"displayableAttributes": ["brand",
"color",
"promotion.type"
],
"facetableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"filterableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"sortableAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"distinctFilterAttributes": {"range": ["age",
"customScore.value",
"salePrice.value"
],
"text": ["brand",
"color",
"promotion.type"
],
"datetime": ["created",
"attributes.modifiedAt"
]
},
"recentSearches": {"windowSize": 100,
"timeSpan": {"type": "DAYS",
"value": 30
}
},
"reranking": {"dynamicReranker": {"enabled": true,
"filter": "string",
"numberOfItems": 1
},
"queryClassification": {"enabled": true,
"actions": [{"action": "staticFilter",
"minReliabilityLevel": "certain"
}
],
"excludedPhrases": ["string"
],
"excludedCategories": ["string"
]
}
},
"geoSearch": {"geoSearchableAttribute": "string"
},
"queryRules": {"consequencesJoinOperators": {"standardFilters": "AND",
"elasticFilters": "AND"
}
},
"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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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:

JWTBasic

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 Deprecated Deprecated parameter. If `query` is provided, this parameter is ignored. If an index has an `id` equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their `name` will be retrieved.
query	string If an index has an `id` equal to the value of this parameter, only that index will be retrieved. Otherwise, all indices containing this value in their `name` will be retrieved. This parameter replaces the deprecated `name` parameter.

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&query=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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:

JWTBasic

Request Body schema: application/json

indexName required	string (SuggestionIndexNameSchema) Name of the suggestion index
description	string (SuggestionIndexDescriptionSchema) Description of the suggestion index
author	integer (SuggestionIndexAuthorSchema) ID of the user who created the suggestion index
enabled required	boolean (SuggestionIndexEnabledSchema) When `true`, index is enabled and can be queried.
required	object (SuggestionIndexSourcesSchema) Sources for the suggestions
	Array of objects (SuggestionIndexDenylistSchema) 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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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:

JWTBasic

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json

indexName required	string (SuggestionIndexNameSchema) Name of the suggestion index
description	string (SuggestionIndexDescriptionSchema) Description of the suggestion index
author	integer (SuggestionIndexAuthorSchema) ID of the user who created the suggestion index
enabled required	boolean (SuggestionIndexEnabledSchema) When `true`, index is enabled and can be queried.
required	object (SuggestionIndexSourcesSchema) Sources for the suggestions
	Array of objects (SuggestionIndexDenylistSchema) 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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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:

JWTBasic

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
directoryId	string <uuid> Requested directoryId of the rule.
search	string Requested part of the name or the id of the rule.

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&directoryId=SOME_STRING_VALUE&search=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{ }
],
"rangeFilters": [{ }
],
"datetimeFilters": [{ }
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"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": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
}
}

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:

JWTBasic

path Parameters

indexId

required

string

ID of the index

Request Body schema: application/json
required

Request for posting a new rule or updating an existing one

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

Responses

Request samples

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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"sortBy": {"attribute": "string",
"ordering": "desc"
},
"customData": "{\"customLandingPage\": \"https://synerise.com/\"}",
"returnNoData": false
}
}
}
}

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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"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:

JWTBasic

path Parameters

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

Request Body schema: application/json
required

Request for posting a new rule or updating an existing one

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

Responses

Request samples

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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"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"
}
},
"datetimeFilters": {"created": {"ranges": [{"rightEnd": {"value": "2024-01-01",
"inclusive": true
}
}
],
"matchingType": "Exact"
}
}
}
},
"queryConsequences": [{"type": "removeWord",
"word": "string",
"replacement": "string"
}
],
"postQueryConsequences": {"hideHits": ["string"
],
"promoteHits": [{"id": "string",
"position": 0
}
],
"promoteHitsPositionStrategy": {"type": "custom"
},
"standardFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"elasticFilters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
},
"boostFilters": [{"weight": -100,
"filters": {"textFilters": [{"attribute": "brand",
"mode": "include",
"values": ["A-Brand",
"B-Brand",
"{brand}"
]
}
],
"rangeFilters": [{"attribute": "price",
"operator": "gt",
"value": "{price}"
}
],
"datetimeFilters": [{"attribute": "created",
"operator": "gt",
"value": "{created}"
}
]
}
}
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 0,
"categoryLevelModifier": 0
},
"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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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: Basic REPLACE_BASIC_AUTH'

Response samples

500

Content type

application/json

{"timestamp": "2019-08-24T14:15:22Z",
"status": 0,
"error": "string",
"message": "string",
"path": "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:

JWTBasic

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. Must be provided with `to`, otherwise the filter is treated as unspecified. 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/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/queries/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500
4xx

Content type

application/json

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

Get top query statistics

Retrieves the 1000 most popular queries.

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

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User, AI API key (legacy)
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:

JWTTrackerKeyBasic

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. Must be provided with `to`, otherwise the filter is treated as unspecified. 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.
withFilters	string Enum: "true" "false" Switch to display search statistics with enabled filters or without filters.
SortBy	string Default: "count" Enum: "count" "clicks" "conversions" "clickThroughRate" "revenue" "conversionRate" Field by which results should be sorted.
ordering	string Default: "desc" Enum: "asc" "desc" Sort order direction.

Responses

Request samples

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

Response samples

200
500
4xx

Content type

application/json

[{"query": "string",
"count": 0,
"clicks": 0,
"clickThroughRate": 0.1,
"revenue": 0.1,
"conversions": 0,
"conversionRate": 0.1
}
]

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:

JWTBasic

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. Must be provided with `to`, otherwise the filter is treated as unspecified. 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.
ordering	string Default: "desc" Enum: "asc" "desc" Sort order direction.

Responses

Request samples

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

Response samples

200
500
4xx

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:

JWTBasic

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. Must be provided with `to`, otherwise the filter is treated as unspecified. 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/4add1a1fa877c1651906bb22c9dfd37a1618852272/stats/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH'

Response samples

200
500
4xx

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:

JWTBasic

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. Must be provided with `to`, otherwise the filter is treated as unspecified. 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: Basic REPLACE_BASIC_AUTH'

Response samples

200
500
4xx

Content type

application/json

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

AI Search (Jan 13, 2026, 11:17:08 AM)

Authorization

Refresh a Profile token

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Authenticate as Profile

Request Body schema: application/json

Responses

Request samples

Response samples

Authenticate Profile with a server

Request Body schema: application/json

Responses

Request samples

Response samples

Authenticate as Profile (conditional)

Authorizations:

Request Body schema: application/json

Responses

Request samples

Response samples

Authenticate anonymously

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Log in as User

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Verify User multi-factor authentication

Authorizations:

query Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Select Workspace

Authorizations:

path Parameters

Responses

Request samples

Response samples

Get Workspaces

Authorizations:

Responses

Request samples

Response samples

Get Workspaces ids with user-specific data

Authorizations:

Responses

Request samples

Response samples

Get current Workspace

Authorizations:

Responses

Request samples

Response samples

Log in as Workspace

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Search

Get deleted searches

Authorizations:

path Parameters

query Parameters

Responses

Request samples

Response samples

Soft-delete a recent search

Authorizations:

path Parameters

query Parameters

Request Body schema: application/jsonrequired

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required