POST
/
toptimize
/
v1
/
retrieval
curl --request POST \
  --url https://api.topsort.com/toptimize/v1/retrieval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "slots": 5,
  "opaqueUserId": "u_9ske45",
  "seedProductIds": [
    "p_PJbnN",
    "p_ojng4"
  ],
  "mode": "all",
  "deviceType": "mobile"
}'
{
  "objectType": "listing",
  "objects": [
    {
      "id": "p_xh90s",
      "value": 0.978
    },
    {
      "id": "p_12lp0",
      "value": 0.953
    },
    {
      "id": "p_ds7ui",
      "value": 0.877
    }
  ],
  "error": false
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
The context information for the predictions, including which metrics to predict.
​
slots
integer
required

How many objects to retrieve.

Example:

10

​
opaqueUserId
string
required

The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to use interactions information to later on provide a prediction of the outcome of the interaction between the user and a product.

Example:

"71303ce0-de89-496d-8270-6434589615e8"

​
seedProductIds
string[]
required
​
mode
enum<string>
default:all
required

Retrieval mode, how to interpret the context to get objects.

Available options:
all,
complement,
similar
​
page
object
​
objectType
enum<string>

The type of object that needs to be retrieved.

Available options:
listings,
banners
​
deviceType
enum<string>

The device the user is on.

Available options:
desktop,
mobile
Example:

"mobile"

Response

200
application/json
The retrieval results. Each retrieved products is accompanied by their relevancy score.
​
objectType
enum<string>
required

The type of object that was predicted.

Available options:
listings,
banners
​
objects
object[]
required

Retrieved objects.