User Interactions

Create One User Interaction

POST users/<str:user_id>/interactions/<str:item_id>/

Note

Authorized Roles: root, manager, backend, frontend

This endpoint allows you to create a new interaction for a user and an item. An inferred rating will be created or updated for the tuple (user_id, item_id). The taste profile of the user will then be updated in real-time by the online machine learning algorithm.

Note: In case the session has already been resolved, the response will include a warning

Request JSON Object
  • interaction_type (string) – [max-length: 64] Interaction type

  • timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

  • properties (object) – Optional. Additional data in interactions

EXAMPLE QUERY BODY
  {
      "interaction_type": "productView",
      "timestamp": 1588812345,
      "properties": {
          "revenue": 19.95
      }
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

Errors:

  • ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

Create Interactions for a User in Bulk

POST users/<str:user_id>/interactions-bulk/

Note

Authorized Roles: root, manager, backend, frontend

Create a small bulk of interactions for a single user and many items. Inferred ratings will be created or updated for all tuples (user_id, item_id).

Request JSON Object
  • interactions (object-array) –

    Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE QUERY BODY
  {
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

Errors:

  • ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

List Interactions of One User In Bulk

GET users/<str:user_id>/interactions-bulk/

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one user. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Query Parameters
  • amt (int) – Optional. [min: 1] Maximal amount of interactions to return

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY PARAMS
  ?amt=3&cursor=F25pU1vHb1LjSEp...
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

  • has_next (bool) – Indicates whether or not there are more interactions to request

  • next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions

  • interactions (object-array) –

    User’s Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE RESPONSE
  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"page": "cart"}},
      ]
  }

Create Interactions for Many Users in Bulk

POST interactions-bulk/

Note

Authorized Roles: root, manager, backend

Create large bulks of interactions for many users and many items. Inferred ratings will be created or updated for all tuples (user_id, item_id).

Note: In case sessions id has already been resolved, they will be created and returned in warnings param

Request JSON Object
  • interactions (object-array) –

    Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

    • user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

EXAMPLE QUERY BODY
  {
      "interactions": [
          {"user_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"user_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"user_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

Errors:

  • ServerUnavailable with error name DB_IMPLICIT_TO_EXPLICIT_PARAMS_NOT_FOUND if no “implicit-to-explicit” parameters have been set for this database

List Interactions for All Users In Bulk

GET interactions-bulk/

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one database. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Parameters start_timestamp and end_timestamp allow filtering out

interactions outside of a specified time frame.

Even when a small time-frame is specified, a full database scan is

performed; in this case, most batches will contain little to no interaction.

Query Parameters
  • amt (int) – Optional. [min: 1] Maximal amount of interactions to return

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

  • start_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Start timestamp of interactions to fetch

  • end_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] End timestamp of interactions to fetch

EXAMPLE QUERY PARAMS
  ?amt=10&cursor=F25pU1vHb1LjSEp...&start_timestamp=1588811110.9&end_timestamp=1588854321.1
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

  • has_next (bool) – Indicates whether or not there are more interactions to request

  • next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions

  • interactions (object-array) –

    Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

    • user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

EXAMPLE RESPONSE
  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"user_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"user_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"user_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Errors:

  • WrongData if both start_timestamp and end_timestamp are provided and start_timestamp >= end_timestamp

Delete Interactions and Ratings for Many Users

DELETE interactions-ratings-bulk/

Note

Authorized Roles: root, manager, backend

Delete all interactions and ratings for many users.

The deletion is done in a background task.

Response JSON Object
  • users_id (ID-array) – Users IDs

EXAMPLE QUERY BODY
  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ]
  }

Create One Anonymous Session Interaction

POST sessions/<str:session_id>/items/<str:item_id>/interactions/

Note

Authorized Roles: root, manager, backend, frontend

This endpoint allows you to create a new interaction for an anonymous session and an item.

Request JSON Object
  • interaction_type (string) – [max-length: 64] Interaction type

  • timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)

  • properties (object) – Optional. Additional data in interactions

EXAMPLE QUERY BODY
  {
      "interaction_type": "productView",
      "timestamp": 1588812345,
      "properties": {
          "revenue": 19.95
      }
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

Create Interactions for an Anonymous Session in Bulk

POST sessions/<str:session_id>/interactions-bulk/

Note

Authorized Roles: root, manager, backend, frontend

Create a small bulk of interactions for a single anonymous session and many items.

Request JSON Object
  • interactions (object-array) –

    Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

EXAMPLE QUERY BODY
  {
      "interactions": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

List Interactions of one Anonymous Session In Bulk

GET sessions/<str:session_id>/interactions-bulk/

Note

Authorized Roles: root, manager, backend

This endpoint allows you to list the interactions of one anonymous session. The response is paginated, you can control the response amount and offset using the query parameters amt and cursor.

Query Parameters
  • amt (int) – Optional. [min: 1] Maximal amount of interactions to return

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY PARAMS
  ?amt=3&cursor=F25pU1vHb1LjSEp...
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

  • has_next (bool) – Indicates whether or not there are more interactions to request

  • next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions

  • interactions (object-array) –

    Anonymous Sessions Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

    • session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE RESPONSE
  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          { "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, , "properties": {"page": "pdp"}},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Create Interactions for Many Anonymous Sessions in Bulk

POST sessions-interactions-bulk/

Note

Authorized Roles: root, manager, backend

Create large bulks of interactions for many anonymous sessions and many items.

Request JSON Object
  • interactions (object-array) –

    Anonymous Session Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

    • session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE QUERY BODY
  {
      "interactions": [
          {"session_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"session_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"session_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

List Interactions for All Anonymous Sessions In Bulk

GET sessions-interactions-bulk/

Note

Authorized Roles: root, manager, backend

List the anonymous session interactions of a database. The response being paginated, you control its size and offset using the query parameters amt and cursor.

Parameters start_timestamp and end_timestamp allow filtering out

interactions outside of a specified time frame.

Query Parameters
  • amt (int) – Optional. [min: 1] Maximal amount of interactions to return

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

  • start_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Start timestamp of interactions to fetch

  • end_timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] End timestamp of interactions to fetch

EXAMPLE QUERY PARAMS
  ?amt=10&cursor=F25pU1vHb1LjSEp...&start_timestamp=1588811110.9&end_timestamp=1588854321.1
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

  • has_next (bool) – Indicates whether or not there are more interactions to request

  • next_cursor (string) – Optional. Pagination cursor, to use in next request to get more interactions

  • interactions (object-array) –

    Anonymous Sessions Interactions array

    Inner fields
    • item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID

    • interaction_type (O) – [max-len:64chars], [max_length: 64] Interaction type

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp

    • properties (object-array) – (additional fields may be present) Additional data in interactions

    • session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

EXAMPLE RESPONSE
  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "interactions": [
          {"session_id": 1234, "item_id": "123e4567-e89b-12d3-a456-426614174000", "interaction_type": "productView", "timestamp": 1588812345, "properties": {"page": "home"}},
          {"session_id": 1234, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "addToCart", "timestamp": 1588854321, "properties": {"page": "pdp"}},
          {"session_id": 333, "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "interaction_type": "productView", "timestamp": 1588811111, "properties": {"revenue": 19.95}}
      ]
  }

Errors:

  • WrongData if both start_timestamp and end_timestamp are provided and start_timestamp >= end_timestamp

Resolve One Anonymous Session

POST sessions/<str:session_id>/resolve/

Note

Authorized Roles: root, manager, backend

This endpoint allows you to resolve an anonymous session with a user. One user can have many anonymous sessions, but an anonymous session can be resolved to a single user.

This endpoint is called from the backend only. When you need to send a new auth token to the frontend after an anonymous user logging-in, is it simpler to resolve and get a new token using POST login/service/ providing both the new frontend_user_id and the old frontend_session_id.

Request JSON Object
  • user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

  • timestamp (float64) – Optional. [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Resolved anonymous session timestamp. Default current time.

EXAMPLE QUERY BODY
  {
      "user_id": "123e4567-e89b-12d3-a456-426614174000",
      "timestamp": 1588812345
  }

Errors:

  • WrongData if the anonymous session was previously resolved

List All Resolved Sessions In Pages

POST resolved-sessions/

Note

Authorized Roles: root, manager, backend

List anonymous sessions resolved. It is possible filter by users ids. The response being paginated, you control its size and offset using the query parameters amt and cursor.

Request JSON Object
  • users_id (ID-array) – Optional. Users IDs

  • amt (int) – Optional. [min: 1] Maximal amount per page

  • cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response

EXAMPLE QUERY BODY
  {
      "users_id": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d"
      ],
      "amt": 10,
      "cursor": "F25pU1vHb1LjSEp..."
  }
Response JSON Object
  • warnings (list-of-string) – Optional. List of warnings

  • resolved_sessions (object-array) –

    Resolved Anonymous Sessions array

    Inner fields
    • session_id (ID) – [see Flexible Identifiers], [max_length: 64] Anonymous Session ID

    • user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID

    • timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Resolved timestamp

  • has_next (bool) – Indicates whether or not there are more anonymous sessions to request

  • next_cursor (string) – Optional. Pagination cursor, to use in next request to get more anonymous sessions

EXAMPLE RESPONSE
  {
      "has_next": true,
      "next_cursor": "Q21vU1pHb1FjSEp...",
      "resolved_sessions": [
          {"session_id": 1234, "user_id": "123e4567-e89b-12d3-a456-426614174000", "timestamp": 1588812345},
          {"session_id": 5678, "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "timestamp": 1588854321},
          {"session_id": 333, "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "timestamp": 1588811111}
      ]
  }